Snapshot of the Umamo working tree as it is

Uploaded as-is from /home/litruv/dev/vtsmaker/umamo on 2026-11-03. 1347 files.
Includes the uncommitted work in progress in :edit, :runtime, and :ui, and the
untracked files under module/edit/src/jvmAndroidMain/.

History is not carried over. The source repo is https://github.com/umamoorg/umamo.
This commit is contained in:
litruv
2026-11-03 18:20:25 +11:00
commit 8bd8fa7a0b
1347 changed files with 246161 additions and 0 deletions
+174
View File
@@ -0,0 +1,174 @@
// :format — Cubism file family + art I/O. KMP library shared by desktop (JVM) and Android.
// :format — Cubism ファイル群とアート入出力。デスクトップ(JVM)と Android が共有する KMP ライブラリ。
plugins {
alias(libs.plugins.kotlinMultiplatform)
alias(libs.plugins.androidKmpLibrary)
alias(libs.plugins.kotlinSerialization)
// Generates the typed CLIP database from module/format/src/commonMain/sqldelight/*.sq.
alias(libs.plugins.sqldelight)
// Umamo's own conventions (gradle/build-logic): the shared jvmAndroidMain source-set group, the
// iosArm64 → `check` wiring, and the corpus/-D forwarding configured by `umamoTestCorpus` below.
id("umamo.kmp-jvmandroid")
id("umamo.kmp-ios-gate")
id("umamo.test-corpus")
}
kotlin {
// One toolchain for every target. Pinned to JDK 21 (LTS) — the build JVM and the
// bytecode level. `jvmToolchain` replaces hand-set sourceCompatibility/targetCompatibility.
jvmToolchain(21)
// NOTE: `-Xexpect-actual-classes` used to live here, opting in to the Beta expect/actual CLASS
// feature (KT-61573) purely because CaffZip was an expect/actual object. It no longer is: the ZIP
// framing is plain commonMain code over the shared DEFLATE seam, and the module's only remaining
// expect is `useClipDatabase`, a top-level fun — which needs no opt-in. Do not add the flag back
// without a declaration that genuinely requires it.
// The `jvmAndroidMain` group this module's CMO3 codec lives in comes from the
// `umamo.kmp-jvmandroid` convention plugin — CMO3 read/write is a JDOM + Kotlin-reflection XML
// serializer (NOT Java object serialization — see docs/format/CMO3.md), and those are JVM-only APIs.
// NOTE: commonMain purity is a COMPILER GUARANTEE in this module, not a convention — the iosArm64
// target below is non-JVM, so `java.*` in commonMain is an unresolved reference rather than a
// latent surprise. (That is not true of a JVM-only module: there, commonMain resolves `java.*`
// happily and the root build's `checkCommonSourcePurity` regex task is the only net.)
jvm()
// The iPadOS target — and the reason commonMain purity is enforceable rather than merely intended.
// Windows, macOS, Linux and Android all run on the JVM (`:desktop` is jvm() packaged per-OS by
// jpackage), so iOS is the ONLY platform here that is not, and the only one that can catch a
// `java.*` leak or a `final`-on-native stdlib inheritance at compile time. It is not a proxy: no
// stand-in target is used, because a stand-in would prove "non-JVM" without proving Apple — and a
// dependency that publishes linuxX64 but not iosArm64 would sail straight through it.
//
// Compiles on Linux and on ubuntu CI: the Kotlin/Native Linux distribution bundles an iOS sysroot
// and the ios_arm64 platform klibs, and :format is a library with no binaries.framework {}, so
// nothing here needs Xcode's linker. Real iPadOS builds and native test runs happen on Apple
// hardware; this target is what makes the daily loop and CI fail fast instead of days later.
//
// iosArm64 is a DEVICE target, so it has no runnable test task — the gate is compile-time, and
// therefore nothing pulls it into `check` on its own; that is what `umamo.kmp-ios-gate` above fixes.
// Add iosSimulatorArm64() if native test EXECUTION on the Mac is wanted.
iosArm64()
// New AGP KMP-aware Android target: declared inside `kotlin {}` (not a separate
// `com.android.library` module). namespace = R class package root.
android {
namespace = "org.umamo.format"
compileSdk = libs.versions.android.compileSdk.get().toInt()
minSdk = libs.versions.android.minSdk.get().toInt()
}
sourceSets {
// The `umamo.kmp-jvmandroid` convention plugin creates this group and wires androidMain onto it;
// it is not a well-known source-set name, so it has no generated accessor and is looked up here.
val jvmAndroidMain = getByName("jvmAndroidMain")
val androidMain = getByName("androidMain")
commonMain.dependencies {
// `api`, not `implementation`: the UMA entry schemas (`uma/puppet/`) are public @Serializable
// classes whose generated companions return KSerializer, so the library is part of this
// module's public surface.
api(libs.kotlinxSerializationJson)
// okio: DEFLATE (its zlibMain source set reaches every target we build, iosArm64 included)
// and Buffer, the growable byte sink the codecs assemble output into. `implementation`,
// not `api`: no okio type appears in :format's public surface.
implementation(libs.okio)
// kotlinx-datetime: the local wall clock CaffZip stamps into the CAFF zip timestamp, to
// match what the official editor writes. The stdlib's common Clock has no time zone and a
// DOS timestamp is local, so this closes the gap without an expect/actual.
implementation(libs.kotlinxDatetime)
}
// Shared by desktop JVM + Android: the CMO3 CAFF/XML codec. JDOM lives here (not jvmMain)
// because the editor's XML serializer must round-trip on both targets — CLAUDE.md keeps
// CMO3 read/write available on Android. JDOM 1.x works on Android via the platform's JAXP.
jvmAndroidMain.dependencies {
implementation(libs.jdom)
// The CMO3 serializer is reflection-driven (declaredMemberProperties, findAnnotation,
// javaField) — those kotlin.reflect.full/.jvm extensions live in kotlin-reflect, not
// the stdlib. Available on Android too, so it stays in the shared source set.
implementation(kotlin("reflect"))
}
jvmMain {
dependencies {
// Driver for CLIP's embedded SQLite database.
implementation(libs.sqldelightSqliteDriver)
}
}
androidMain.dependencies {
// Driver for CLIP's embedded SQLite database.
implementation(libs.sqldelightAndroidDriver)
}
// nativeMain, not iosArm64Main: the default hierarchy makes it the parent of appleMain, so the
// actual here already covers any further Apple target (a simulator, say) without moving.
nativeMain.dependencies {
// Driver for CLIP's embedded SQLite database (SQLiter under the hood).
implementation(libs.sqldelightNativeDriver)
// The native actual writes the extracted database to a temp file; okio is the only
// filesystem the common source sets have.
implementation(libs.okio)
}
commonTest {
dependencies {
implementation(kotlin("test"))
}
}
jvmTest {
dependencies {
// The synthetic CLIP fixture (ClipSyntheticReaderTest) drives the JDBC driver directly
// to generate its database. jvmMain already carries the driver, but the test's use is
// its own - declared here so it survives the driver ever moving out of jvmMain.
implementation(libs.sqldelightSqliteDriver)
}
}
}
}
// SQLDelight: generate a typed ClipDatabase from src/commonMain/sqldelight/.../Clip.sq.
sqldelight {
databases {
create("ClipDatabase") {
packageName.set("org.umamo.format.clip.db")
}
}
}
// Corpus wiring for the sample-gated tests (the `umamo.test-corpus` convention plugin). Explicit `-D`
// wins, the local golden corpus is the default, and absent both the test self-skips — see
// org.umamo.buildlogic.resolveCorpusSample in gradle/build-logic for the rules and why they are what
// they are.
//
// Most art readers (kra/clip/psd/tiff/jpeg/png/webp) additionally auto-discover test/corpus by walking
// up from the test working directory, so they need no default here — their entries exist only so an
// explicit `-D` can override. `bmp.sample` was dropped: nothing reads it.
umamoTestCorpus {
maxHeap("4g")
sample(
"cmo3.sample",
// Forwarded so AllVersionsGateTest can run at all — it was omitted here, so the
// cross-version parity gate could never see its property and always skipped.
"cmo3.probe",
// The MOC3 decode/lowering/bake/probe gates walk the whole moc3 corpus - without this they
// silently self-skipped on a plain `:format:jvmTest`.
"moc3.samples",
"kra.sample",
"clip.sample",
"psd.sample",
"png.sample",
"tiff.sample",
"webp.sample",
"jpeg.sample",
// ModelGenerator's input set. Defaults to the whole cmo3/ corpus so the generated model is the
// union across every sample (see sharedCorpusDefault).
"cmo3.gensample",
// Cmo3ResaveDumpTest's input list. Explicit-only (the shared table has no entry), so the resave
// dump never floods build/ on a plain test run.
"cmo3.resave",
)
// 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.
flag("cmo3.generate")
}
@@ -0,0 +1,67 @@
package org.umamo.format.clip
import android.content.Context
import androidx.sqlite.db.SupportSQLiteDatabase
import app.cash.sqldelight.driver.android.AndroidSqliteDriver
import org.umamo.format.clip.db.ClipDatabase
import java.io.File
/**
* Android app hook for the CLIP reader. Set [applicationContext] once at startup (from your
* Application or Activity, the same way the app calls FileKit.init): the Android SQLite driver needs
* a Context to locate a database file, but the format-neutral ArtReader.read(bytes) has none, so it
* is supplied here. Prefer the application context to avoid leaking an Activity.
*
* Android 用フック。起動時に applicationContext を一度設定する(Context が必要なため)。
*/
object ClipAndroid {
// TODO(android-clip): currently assigned nowhere - the Android app has no file-open flow yet, so
// CLIP is unreachable there and this hook is inert. When Android gains an open path, set
// `ClipAndroid.applicationContext = applicationContext` in MainActivity.onCreate (where a future
// FileKit.init(this) will also go), or reading a .clip will fail the error() in useClipDatabase.
@Volatile
var applicationContext: Context? = null
}
/**
* Android actual: write the database bytes into the app's databases dir and open the SQLDelight
* AndroidSqliteDriver over it. A no-op callback skips schema creation/migration - the embedded .clip
* database already has its tables (and carries user_version 0, which would otherwise trigger
* onCreate -> Schema.create and collide with the existing tables).
*
* @param ByteArray databaseBytes The raw "SQLite format 3" bytes.
* @param Function1 block Runs against the open database.
* @return T The block's result.
*/
internal actual fun <T> useClipDatabase(databaseBytes: ByteArray, block: (ClipDatabase) -> T): T {
val context =
ClipAndroid.applicationContext
?: error("ClipReader on Android requires ClipAndroid.applicationContext to be set at startup")
// A short-lived DB under the app's databases dir; AndroidSqliteDriver(name) opens the same path.
val name = "umamo-clip-${System.nanoTime()}.sqlite3"
val databaseFile = context.getDatabasePath(name)
databaseFile.parentFile?.mkdirs()
databaseFile.writeBytes(databaseBytes)
try {
// Skip Schema.create/migrate: the file already is a complete CLIP database.
val callback =
object : AndroidSqliteDriver.Callback(ClipDatabase.Schema) {
override fun onCreate(db: SupportSQLiteDatabase) = Unit
override fun onUpgrade(db: SupportSQLiteDatabase, oldVersion: Int, newVersion: Int) = Unit
}
val driver = AndroidSqliteDriver(schema = ClipDatabase.Schema, context = context, name = name, callback = callback)
try {
return block(ClipDatabase(driver))
} finally {
driver.close()
}
} finally {
databaseFile.delete()
// SQLite may create sidecar journal/WAL files next to the database; remove them too.
File("${databaseFile.path}-wal").delete()
File("${databaseFile.path}-shm").delete()
File("${databaseFile.path}-journal").delete()
}
}
@@ -0,0 +1,145 @@
package org.umamo.format
/**
* What the editor does with a file, as the file's kind declares it.
*
* The distinction is not about which codec reads the bytes - it is about which way in a file takes. A
* document REPLACES what is open (behind the unsaved-changes gate); artwork is ADDED to the document
* that is already open, the way importing an object into a Blender scene adds to it. A sidecar is
* neither: it is found beside a file the editor opened, never handed over on its own.
*/
enum class FileRole {
/** Opens as the whole document: the native `.uma`, and the CMO3 / MOC3 the editor imports. */
Document,
/** Ingested as source art into the open document: the layered formats and the flat rasters. */
Artwork,
/** Read beside a document, never opened as one: the MOC3 JSON family. */
Sidecar,
}
/**
* The file families Umamo understands, plus the art-source formats it ingests.
*
* Modelled as a `sealed interface` so a `when` over kinds is exhaustive (the compiler rejects an
* unhandled case) - the same enforcement applied to [Cmo3Version]. Each kind declares its
* capabilities ([readable]/[writable]/[role]), so dispatch and UI can reason about support without a
* scattered list of booleans, and its [extension] (with any [extensionAliases]), so nothing else
* spells the extension by hand.
*/
sealed interface FileKind {
/** Conventional file extension without the dot, e.g. `"cmo3"`. */
val extension: String
/**
* Other extensions the same format is written under, without the dot.
*
* Detection is by magic bytes, so an alias only matters where the name is the only signal - the
* extension fallback in [FormatRegistry.kindForFileName] and the picker filters built from it.
*/
val extensionAliases: List<String> get() = emptyList()
val readable: Boolean
val writable: Boolean
/** Which way into the editor a file of this kind takes. */
val role: FileRole
// --- Umamo UMA!~ ---
data object Uma : FileKind {
override val extension = "uma"
override val readable = true
override val writable = true
override val role = FileRole.Document
}
// --- Live2D Cubism CMO3 Puppet Model ---
data object Cmo3 : FileKind {
override val extension = "cmo3"
override val readable = true
override val writable = true
override val role = FileRole.Document
}
// --- Live2D Cubism MOC3 Puppet Model ---
data object Moc3 : FileKind {
override val extension = "moc3"
override val readable = true
override val writable = true
override val role = FileRole.Document
}
// --- Live2D Cubism MOC3 Puppet Model Sidecar Files - model3/physics3/cdi3/pose3/exp3/motion3/userdata3. ---
data object Json : FileKind {
override val extension = "json"
override val readable = true
override val writable = true
override val role = FileRole.Sidecar
}
// --- Adobe Photoshop PSD Layered Artwork ---
data object Psd : FileKind {
override val extension = "psd"
override val readable = true
override val writable = false
override val role = FileRole.Artwork
}
// --- Clip Studio Paint CLIP Layered Artwork ---
data object Clip : FileKind {
override val extension = "clip"
override val readable = true
override val writable = false
override val role = FileRole.Artwork
}
// --- Krita KRA Layered Artwork ---
data object Kra : FileKind {
override val extension = "kra"
override val readable = true
override val writable = false
override val role = FileRole.Artwork
}
// --- PNG Raster Artwork ---
data object Png : FileKind {
override val extension = "png"
override val readable = true
override val writable = true
override val role = FileRole.Artwork
}
// --- BMP Raster Artwork ---
data object Bmp : FileKind {
override val extension = "bmp"
override val readable = true
override val writable = true
override val role = FileRole.Artwork
}
// --- JPEG Raster Artwork ---
data object Jpeg : FileKind {
override val extension = "jpg"
override val extensionAliases = listOf("jpeg")
override val readable = true
override val writable = false
override val role = FileRole.Artwork
}
// --- WEBP Raster Artwork ---
data object WebP : FileKind {
override val extension = "webp"
override val readable = true
override val writable = false
override val role = FileRole.Artwork
}
// --- TIFF Raster Artwork ---
data object Tiff : FileKind {
override val extension = "tiff"
override val extensionAliases = listOf("tif")
override val readable = true
override val writable = false
override val role = FileRole.Artwork
}
}
@@ -0,0 +1,78 @@
package org.umamo.format
/**
* The shared read/write contract for one binary container format in the Cubism/Umamo file family.
*
* EN: Every format Umamo can both parse and emit as a self-contained byte stream (today `.cmo3` and
* `.moc3`; later `.uma`) exposes the same members, so callers and the [FormatRegistry]
* dispatcher treat formats uniformly instead of hardcoding one facade's method names. The
* in-memory model type differs per format ([org.umamo.format.cmo3.Cmo3Model] vs
* [org.umamo.format.moc3.moc.MocModel]) and the two share no supertype - hence the generic
* [TModel]; a heterogeneous registry holds `FormatCodec<*>` and callers branch on [kind]. The
* dependency runs codec → [FileKind] (a codec names its kind), never the reverse, so [FileKind]
* stays pure metadata. Text sidecars (`model3.json` and friends) are `String`-shaped, not
* `ByteArray`, so they deliberately fall outside this contract.
* JA: `.cmo3`/`.moc3` など「バイト列で完結する」形式の共通読み書き契約。モデル型は形式ごとに異なる。
*/
public interface FormatCodec<TModel> {
/** Which [FileKind] this codec reads and writes - the link to capability/tier metadata. */
public val kind: FileKind
/**
* Cheap magic-byte sniff: whether [candidateBytes] plausibly belongs to this format.
*
* Intended to be allocation-light (inspect only the leading magic), so [FormatRegistry] can try
* every codec against a file without fully parsing it.
*
* @param ByteArray candidateBytes The file contents to test.
* @return Boolean True if the leading bytes match this format's signature.
*/
public fun matches(candidateBytes: ByteArray): Boolean
/**
* Cheap version probe: the format version carried by [bytes], without a full [read].
*
* Implementations must stay lightweight next to [read] (decode only what the version requires)
* and must not throw on malformed or unknown input - null covers both "this codec exposes no
* version" (the default, kept by the layered-art readers) and "no version could be determined".
*
* @param ByteArray bytes The complete file contents.
* @return FormatVersion? The probed version, or null when unavailable.
*/
public fun getVersion(bytes: ByteArray): FormatVersion? = null
/**
* Parses a complete file into this format's in-memory model.
*
* @param ByteArray bytes The complete file contents.
* @return TModel The parsed model.
*/
public fun read(bytes: ByteArray): TModel
/**
* Serializes a model back to a complete file.
*
* @param TModel model The model to write.
* @return ByteArray The complete file bytes.
*/
public fun write(model: TModel): ByteArray
}
/**
* A [FormatCodec] for a format Umamo reads but never emits - the layered-art ingestion sources
* (PSD, CLIP, KRA), whose [FileKind] already declares `writable = false`. Inherits a [write] that
* refuses, so the read-only nature is stated once in the type instead of copy-pasted throws in each
* reader; the [FormatRegistry] still holds these uniformly as `FormatCodec<*>`.
*
* 読み取り専用形式(PSD/CLIP/KRA などの画材取り込み元)用の FormatCodec。write は常に拒否する。
*/
public interface ReadOnlyCodec<TModel> : FormatCodec<TModel> {
/**
* Always refuses: this format is ingestion-only.
*
* @param TModel model Ignored.
* @return ByteArray Never returns.
*/
override fun write(model: TModel): ByteArray =
throw UnsupportedOperationException("${kind.extension.uppercase()} is read-only")
}
@@ -0,0 +1,22 @@
package org.umamo.format
/**
* A probed format version, the common face over each codec's own version type.
*
* [org.umamo.format.moc3.moc.MocVersion] (an enum) and [org.umamo.format.cmo3.Cmo3Version] (a
* sealed interface) share no other supertype - mirroring how the codec model types share none -
* so this marker is what lets [FormatCodec.getVersion] report a version uniformly. Not to be
* confused with the serialized CMO3 model enum `org.umamo.format.cmo3.model.gen.FormatVersion`,
* which is format data inside the document, not a probe result.
*/
public interface FormatVersion {
/** Short human-readable token naming the version (e.g. "cmo3 / Cubism 4.x"). */
public val label: String
/**
* A human-readable support summary for this version.
*
* @return String The summary sentence.
*/
public fun describe(): String
}
@@ -0,0 +1,230 @@
package org.umamo.format.art
/**
* Default alpha threshold: a pixel counts as opaque when its alpha byte is at least this value.
*
* 1 means any nonzero alpha counts, which keeps the trimmed bounds lossless for the atlas
* packer: no antialiased edge pixel (alpha 1..10) is ever cut away, so nothing visible can be
* clipped at an atlas tile boundary. Consumers wanting a stricter silhouette (the auto-mesh)
* pass a higher threshold instead of changing this default.
*/
public const val DEFAULT_ALPHA_THRESHOLD: Int = 1
/**
* Default Douglas-Peucker simplification tolerance for the alpha contour, in pixels.
*
* 1.0 collapses the unit staircase that a 45 degree antialiased edge traces (maximum deviation
* from the true diagonal is sqrt(2)/2, about 0.707 px) into single segments, while the
* Douglas-Peucker guarantee keeps the simplified polygon within one pixel of the exact mask
* boundary. 0 keeps the exact lattice ring.
*/
public const val DEFAULT_CONTOUR_EPSILON: Float = 1.0f
/**
* The opaque-region description of one raster: pixel-tight trimmed bounds, an occupancy
* summary, and the boundary contour(s) of the thresholded alpha mask. This is the shared
* foundation the atlas packer (trimmed rects) and the auto-mesh (silhouette) both consume.
*
* A plain class, not a data class: it holds contour point arrays (via [contours]) for which
* generated structural equality would deep-compare arrays. Identity equality is the right
* default, matching [LayerRaster].
*/
public class AlphaAnalysis(
/**
* Pixel-tight bounds of the opaque region, RASTER-LOCAL: left/top are relative to the
* raster's own origin, not the source canvas. Offset by the layer's canvas position via
* [opaqueBoundsOnCanvas] when canvas space is needed.
*/
public val opaqueBounds: LayerBounds,
/** Number of pixels whose alpha met the threshold. */
public val opaquePixelCount: Int,
/**
* Boundary contours of the thresholded alpha mask, raster-local, one per opaque island
* plus one per enclosed hole ([AlphaContour.isHole]). Never empty on a non-null analysis,
* and always contains at least one non-hole contour.
*/
public val contours: List<AlphaContour>,
) {
/** Fraction of the trimmed bounds covered by opaque pixels, in 0.0..1.0. */
public val boundsCoverage: Float
get() = opaquePixelCount.toFloat() / (opaqueBounds.width.toFloat() * opaqueBounds.height.toFloat())
}
/**
* One closed boundary loop of the thresholded alpha mask.
*
* Points are integer pixel-corner lattice coordinates (x in 0..width, y in 0..height, y down),
* raster-local: a contour point is a corner BETWEEN pixels, not a pixel center, so pixel
* (column, row) occupies the unit square [column, column+1] x [row, row+1] and the polygon is
* watertight and pixel-exact. Closure is implicit: the last point connects back to the first
* (they are never equal). Winding encodes the region side: walking the ring keeps opaque
* pixels on the right (y-down), so outer contours have positive shoelace area and holes have
* negative. [isHole] is derived from the exact ring and is the authoritative flag: the
* winding redundancy is guaranteed only for exact rings (contourEpsilon 0), because an
* adversarially self-intersecting simplified ring's shoelace sign may disagree (the known
* simplifier limitation) — do not re-derive hole-ness from a simplified ring's winding.
*
* A contour may touch itself at a saddle corner (a repeated non-consecutive vertex, "weakly
* simple"); it never crosses itself.
*
* A plain class, not a data class: it wraps a point array for which generated structural
* equality would deep-compare on every call.
*/
public class AlphaContour(
/** Flattened corner coordinates x0, y0, x1, y1, ...; the final point connects to the first. */
public val points: IntArray,
/** True when this loop encloses a transparent hole inside an opaque island. */
public val isHole: Boolean,
)
/**
* Analyzes the opaque region of an RGBA8888 straight-alpha raster (top row first): pixel-tight
* trimmed bounds, opaque pixel count, and the traced boundary contours, optionally simplified.
*
* Despite the file's "alpha analysis" theme this is NOT an Edelsbrunner alpha shape (no
* Delaunay parameter); it is a threshold mask description: a scan for bounds and count, a
* marching-squares style boundary trace on the pixel-corner lattice, and Douglas-Peucker
* simplification. Output is fully deterministic for a given input, which downstream repacking
* relies on.
*
* Returns null if and only if no pixel meets [alphaThreshold] — including the 0x0 raster and
* the 1x1 transparent placeholders the CLIP/KRA readers emit for empty layers. Slivers with
* real opaque pixels (1 px wide or tall) are reported with their true bounds; excluding them
* is consumer policy, so a genuine hairline art layer is never dropped here.
*
* @param Int width Raster width in pixels; may be 0.
* @param Int height Raster height in pixels; may be 0.
* @param ByteArray rgba RGBA8888 pixels, straight alpha, row-major from the top row; exactly width * height * 4 bytes.
* @param Int alphaThreshold Minimum alpha byte value (1..255) for a pixel to count as opaque.
* @param Float contourEpsilon Douglas-Peucker tolerance in pixels; 0 keeps the exact lattice rings.
* @return AlphaAnalysis The RASTER-LOCAL opaque-region description (bounds and contours are
* relative to the raster's own origin, not the source canvas), or null when nothing
* meets the threshold.
*/
public fun analyzeAlpha(
width: Int,
height: Int,
rgba: ByteArray,
alphaThreshold: Int = DEFAULT_ALPHA_THRESHOLD,
contourEpsilon: Float = DEFAULT_CONTOUR_EPSILON,
): AlphaAnalysis? {
require(width >= 0 && height >= 0) { "raster dimensions must be non-negative: $width x $height" }
require(rgba.size.toLong() == width.toLong() * height.toLong() * 4L) {
"rgba size ${rgba.size} does not match $width x $height x 4"
}
require(alphaThreshold in 1..255) {
"alphaThreshold must be in 1..255 (0 marks everything opaque, 256 nothing): $alphaThreshold"
}
require(contourEpsilon >= 0f) { "contourEpsilon must be non-negative: $contourEpsilon" }
// Pass 1: one row-major sweep folds the trimmed bounds and the count, and builds the
// bit-packed mask the tracer walks. Packed LongArray, not BooleanArray: an 8192^2 layer
// is 67M pixels — 8.4 MB packed versus 67 MB boolean, and the tracer needs a second
// same-geometry bitset (Android heap decides this).
val pixelCount = width * height
val maskWords = LongArray((pixelCount + 63) ushr 6)
var opaquePixelCount = 0
var minRow = Int.MAX_VALUE
var maxRow = -1
var minColumn = Int.MAX_VALUE
var maxColumn = -1
var pixelIndex = 0
for (rowIndex in 0 until height) {
for (columnIndex in 0 until width) {
// The `and 0xFF` is load-bearing: Kotlin Byte is signed, so alpha 128..255 reads
// negative without it and a >= threshold compare silently drops those pixels.
val alpha = rgba[pixelIndex * 4 + 3].toInt() and 0xFF
if (alpha >= alphaThreshold) {
opaquePixelCount++
maskWords[pixelIndex ushr 6] = maskWords[pixelIndex ushr 6] or (1L shl (pixelIndex and 63))
if (rowIndex < minRow) {
minRow = rowIndex
}
if (rowIndex > maxRow) {
maxRow = rowIndex
}
if (columnIndex < minColumn) {
minColumn = columnIndex
}
if (columnIndex > maxColumn) {
maxColumn = columnIndex
}
}
pixelIndex++
}
}
if (opaquePixelCount == 0) {
return null
}
val opaqueBounds =
LayerBounds(
left = minColumn,
top = minRow,
width = maxColumn - minColumn + 1,
height = maxRow - minRow + 1,
)
val mask = AlphaMask(width, height, maskWords)
val exactContours = traceAlphaContours(mask, opaqueBounds)
val contours =
if (contourEpsilon > 0f) {
exactContours.map { contour ->
// simplifyClosedRing returns the input array itself when nothing can drop;
// reuse the contour object then instead of re-wrapping the same ring.
val simplifiedPoints = simplifyClosedRing(contour.points, contourEpsilon)
if (simplifiedPoints === contour.points) {
contour
} else {
AlphaContour(simplifiedPoints, contour.isHole)
}
}
} else {
exactContours
}
return AlphaAnalysis(opaqueBounds, opaquePixelCount, contours)
}
/**
* Analyzes this layer raster's opaque region. See the positional [analyzeAlpha] for the full
* contract.
*
* @param Int alphaThreshold Minimum alpha byte value (1..255) for a pixel to count as opaque.
* @param Float contourEpsilon Douglas-Peucker tolerance in pixels; 0 keeps the exact lattice rings.
* @return AlphaAnalysis The opaque-region description, or null when nothing meets the threshold.
*/
public fun LayerRaster.analyzeAlpha(
alphaThreshold: Int = DEFAULT_ALPHA_THRESHOLD,
contourEpsilon: Float = DEFAULT_CONTOUR_EPSILON,
): AlphaAnalysis? = analyzeAlpha(width, height, rgba, alphaThreshold, contourEpsilon)
/**
* Analyzes this layer's opaque region from its stored raster pixels.
*
* Deliberately ignores the layer's compositing properties — opacity, visible, blend, and
* channelMask describe how the pixels composite, not what is stored, and applying them is
* consumer policy. Results are raster-local; use [opaqueBoundsOnCanvas] with
* [SourceLayer.bounds] for canvas space.
*
* @param Int alphaThreshold Minimum alpha byte value (1..255) for a pixel to count as opaque.
* @param Float contourEpsilon Douglas-Peucker tolerance in pixels; 0 keeps the exact lattice rings.
* @return AlphaAnalysis The opaque-region description, or null when nothing meets the threshold.
*/
public fun SourceLayer.analyzeAlpha(
alphaThreshold: Int = DEFAULT_ALPHA_THRESHOLD,
contourEpsilon: Float = DEFAULT_CONTOUR_EPSILON,
): AlphaAnalysis? = raster.analyzeAlpha(alphaThreshold, contourEpsilon)
/**
* Converts the raster-local trimmed bounds to source-canvas space by offsetting with the
* layer's canvas position ([SourceLayer.bounds] left/top).
*
* @param LayerBounds layerBounds The layer's position on the source canvas.
* @return LayerBounds The trimmed opaque bounds in source-canvas space.
*/
public fun AlphaAnalysis.opaqueBoundsOnCanvas(layerBounds: LayerBounds): LayerBounds =
LayerBounds(
left = layerBounds.left + opaqueBounds.left,
top = layerBounds.top + opaqueBounds.top,
width = opaqueBounds.width,
height = opaqueBounds.height,
)
@@ -0,0 +1,236 @@
package org.umamo.format.art
/**
* A bit-packed boolean mask over a raster's pixels, one bit per pixel, row-major from the top.
*
* Out-of-range coordinates read as transparent so the boundary tracer needs no padding ring
* around the raster. Packed into a LongArray rather than a BooleanArray because the tracer's
* inputs can be large (an 8192^2 layer is 67M pixels) and two same-geometry bitsets are alive
* at once during tracing.
*
* @param Int width Mask width in pixels.
* @param Int height Mask height in pixels.
* @param LongArray words The packed bits, bit (rowIndex * width + columnIndex).
*/
internal class AlphaMask(
val width: Int,
val height: Int,
private val words: LongArray,
) {
/**
* Whether the pixel at the given coordinates is opaque; out-of-range is transparent.
*
* @param Int columnIndex Pixel column, any value.
* @param Int rowIndex Pixel row, any value.
* @return Boolean True when in range and the mask bit is set.
*/
fun isOpaque(columnIndex: Int, rowIndex: Int): Boolean {
if (columnIndex < 0 || columnIndex >= width || rowIndex < 0 || rowIndex >= height) {
return false
}
val pixelIndex = rowIndex * width + columnIndex
return (words[pixelIndex ushr 6] and (1L shl (pixelIndex and 63))) != 0L
}
}
/**
* A growable flat (x, y) point accumulator for contour tracing, doubling on demand.
*
* Exists because commonMain has no java.util growable primitives and boxing every lattice
* corner into a List would swamp the trace loop on large contours.
*/
private class ContourPointBuffer {
private var storage = IntArray(INITIAL_CAPACITY)
private var size = 0
/**
* Appends one point.
*
* @param Int x Lattice corner x.
* @param Int y Lattice corner y.
*/
fun add(x: Int, y: Int) {
if (size + 2 > storage.size) {
storage = storage.copyOf(storage.size * 2)
}
storage[size] = x
storage[size + 1] = y
size += 2
}
/** The accumulated points as a right-sized flat array. */
fun toArray(): IntArray = storage.copyOf(size)
private companion object {
const val INITIAL_CAPACITY = 32
}
}
/**
* Twice the signed shoelace area of a closed flat-point ring (implicit closure, y-down).
*
* Under the tracer's opaque-on-the-right winding, outer contours are positive and holes are
* negative, and the signed areas of all contours of one mask sum to exactly twice the opaque
* pixel count — the tracer's core invariant, which tests assert. Long because a full-canvas
* ring at PSB scale overflows Int.
*
* @param IntArray points Flattened x0, y0, x1, y1, ... ring; last point connects to the first.
* @return Long Twice the signed area.
*/
internal fun signedAreaTwice(points: IntArray): Long {
var doubledArea = 0L
val pointCount = points.size / 2
for (pointIndex in 0 until pointCount) {
val nextIndex = if (pointIndex + 1 == pointCount) 0 else pointIndex + 1
val x = points[pointIndex * 2].toLong()
val y = points[pointIndex * 2 + 1].toLong()
val nextX = points[nextIndex * 2].toLong()
val nextY = points[nextIndex * 2 + 1].toLong()
doubledArea += x * nextY - nextX * y
}
return doubledArea
}
/**
* Traces every closed boundary contour of the mask — outer island boundaries and enclosed
* holes — as exact pixel-corner lattice rings.
*
* This is boundary tracing on the pixel-corner lattice (the axis-aligned "outline of the
* union of pixel squares"), not the midpoint-interpolating marching-squares isoline, which
* would offset every polygon by half a pixel and cut corners. The walk keeps opaque pixels
* on the right of the travel direction (y-down), so outer contours come out with positive
* shoelace area and holes negative. Saddle corners (the two diagonal pixels opaque) take the
* tight right turn, i.e. 4-connected foreground / 8-connected background: a diagonal
* checkerboard traces as separate unit squares and loops never cross themselves (though one
* loop may touch itself at a saddle corner). Vertices are emitted only where the heading
* changes, so straight runs carry no interior points and the exact ring is already minimal.
*
* Discovery is a row-major scan restricted to the trimmed bounds: every loop, outer or hole,
* contains at least one "north edge" (transparent-or-border pixel above, opaque pixel below),
* which this winding always walks eastward, so marking traversed north edges in one extra
* bitset makes each loop discoverable exactly once. The scan order also pins determinism —
* each contour starts at its topmost-then-leftmost north edge and contours are listed in that
* discovery order — which downstream repacking relies on. Total cost is one bounds-restricted
* mask scan plus O(total boundary length).
*
* Worst case to know about: a 50 percent checkerboard-noise mask yields one unit-square
* contour per opaque pixel (millions of tiny rings on a large layer). Pathological input; no
* mitigation here.
*
* @param AlphaMask mask The thresholded pixel mask; must contain at least one opaque pixel.
* @param LayerBounds opaqueBounds The pixel-tight trimmed bounds of the mask's opaque pixels.
* @return List The traced contours; never empty, at least one non-hole.
*/
internal fun traceAlphaContours(mask: AlphaMask, opaqueBounds: LayerBounds): List<AlphaContour> {
val contours = mutableListOf<AlphaContour>()
// Bit per pixel: set when the north edge of that pixel (the edge to the pixel above) has
// been walked. Same geometry as the mask itself.
val northEdgeVisited = LongArray(((mask.width * mask.height) + 63) ushr 6)
for (rowIndex in opaqueBounds.top until opaqueBounds.top + opaqueBounds.height) {
for (columnIndex in opaqueBounds.left until opaqueBounds.left + opaqueBounds.width) {
if (!mask.isOpaque(columnIndex, rowIndex)) {
continue
}
if (mask.isOpaque(columnIndex, rowIndex - 1)) {
continue
}
val edgeIndex = rowIndex * mask.width + columnIndex
if ((northEdgeVisited[edgeIndex ushr 6] and (1L shl (edgeIndex and 63))) != 0L) {
continue
}
contours.add(traceLoop(mask, northEdgeVisited, columnIndex, rowIndex))
}
}
return contours
}
/**
* Walks one closed boundary loop starting from the north edge of the given opaque pixel,
* heading east, and returns its ring with the hole flag derived from the shoelace sign.
*
* Walk invariant: every traversed lattice edge has an opaque pixel on its right and a
* transparent one on its left (relative to the travel direction, y-down). At each corner the
* two pixels flanking the edge straight ahead pick the turn:
*
* left opaque, right opaque -> turn left (hug the corner)
* left clear, right opaque -> straight
* left clear, right clear -> turn right (round the corner)
* left opaque, right clear -> saddle -> tight right turn (4-connected foreground)
*
* The loop terminates when it is about to re-traverse the starting directed edge (same corner
* AND same heading — the corner alone is not enough, because a weakly simple loop may pass
* through the start corner again with a different heading). Every eastward edge walked is by
* construction the north edge of the opaque pixel below it, and is marked in the visited
* bitset so discovery never starts this loop twice.
*
* @param AlphaMask mask The thresholded pixel mask.
* @param LongArray northEdgeVisited Bit per pixel, set here for every eastward edge walked.
* @param Int startColumn Column of the opaque pixel whose north edge starts the loop.
* @param Int startRow Row of the opaque pixel whose north edge starts the loop.
* @return AlphaContour The traced ring.
*/
private fun traceLoop(
mask: AlphaMask,
northEdgeVisited: LongArray,
startColumn: Int,
startRow: Int,
): AlphaContour {
val points = ContourPointBuffer()
var cornerX = startColumn
var cornerY = startRow
var headingX = 1
var headingY = 0
// The start corner is always a genuine vertex: the walk can only enter it turning (the
// pixel to its west having a north edge on the same loop would have been discovered
// first), so emitting it up front never duplicates a straight-run point.
points.add(cornerX, cornerY)
while (true) {
if (headingX == 1) {
// An eastward edge always has its opaque pixel below (opaque-on-right), so the
// below pixel (cornerX, cornerY) is in range and this is its north edge.
val edgeIndex = cornerY * mask.width + cornerX
northEdgeVisited[edgeIndex ushr 6] = northEdgeVisited[edgeIndex ushr 6] or (1L shl (edgeIndex and 63))
}
cornerX += headingX
cornerY += headingY
// The two pixels flanking the edge straight ahead. The quadrant offsets reduce to
// these closed forms; each division operand is always -2 or 0, so truncation is exact.
val leftOpaque =
mask.isOpaque(
cornerX + (headingX + headingY - 1) / 2,
cornerY + (headingY - headingX - 1) / 2,
)
val rightOpaque =
mask.isOpaque(
cornerX + (headingX - headingY - 1) / 2,
cornerY + (headingY + headingX - 1) / 2,
)
val newHeadingX: Int
val newHeadingY: Int
if (leftOpaque && rightOpaque) {
// Turn left.
newHeadingX = headingY
newHeadingY = -headingX
} else if (rightOpaque) {
// Straight on.
newHeadingX = headingX
newHeadingY = headingY
} else {
// Both clear, or the diagonal saddle (left opaque, right clear): turn right. The
// saddle right turn is the 4-connected-foreground policy — diagonal-only contact
// separates rather than merges.
newHeadingX = -headingY
newHeadingY = headingX
}
if (cornerX == startColumn && cornerY == startRow && newHeadingX == 1 && newHeadingY == 0) {
break
}
if (newHeadingX != headingX || newHeadingY != headingY) {
points.add(cornerX, cornerY)
}
headingX = newHeadingX
headingY = newHeadingY
}
val ring = points.toArray()
return AlphaContour(ring, isHole = signedAreaTwice(ring) < 0L)
}
@@ -0,0 +1,199 @@
package org.umamo.format.art
/**
* A growable Int stack for the iterative Douglas-Peucker range walk.
*
* Exists because contours can carry 100k+ vertices and a recursive formulation would gamble
* on Kotlin/Native stack depth in commonMain; java.util.ArrayDeque is unavailable here.
*/
private class IntStack {
private var storage = IntArray(INITIAL_CAPACITY)
private var size = 0
/**
* Pushes one value.
*
* @param Int value The value to push.
*/
fun push(value: Int) {
if (size == storage.size) {
storage = storage.copyOf(storage.size * 2)
}
storage[size] = value
size++
}
/** Removes and returns the top value; the caller guarantees non-emptiness. */
fun pop(): Int {
size--
return storage[size]
}
/** Whether any values remain. */
fun isNotEmpty(): Boolean = size > 0
private companion object {
const val INITIAL_CAPACITY = 64
}
}
/**
* Simplifies a closed lattice ring with Douglas-Peucker, returning a subset of its vertices.
*
* Closed rings get the standard two-anchor treatment: anchor A is ring index 0 (the tracer's
* deterministic topmost-then-leftmost start vertex) and anchor B is the vertex farthest from A
* (ties resolve to the lowest index); the two open halves A->B and B->A are simplified
* independently, so both anchors always survive. The walk is iterative over an explicit range
* stack. Distances are exact until the final comparison: Long integer dot and cross products,
* squared distance to the clamped segment (robust for halves that double back), and a strict
* greater-than against epsilon squared, so epsilon 0 drops exactly-collinear vertices and
* nothing else.
*
* Guarantees: every kept vertex is an original lattice vertex on the exact mask boundary, and
* every dropped vertex lies within epsilon pixels of a segment of the simplified ring (the
* Douglas-Peucker construction), so the result deviates from the exact boundary by at most
* epsilon. If simplification would leave fewer than 3 points (a 1xN sliver's rectangle at
* epsilon 1 collapses to its two anchors), the unsimplified ring is returned instead. Output
* is deterministic.
*
* Known limitation, accepted for v1: on adversarial shapes Douglas-Peucker can produce a
* self-intersecting simplified ring. Callers needing a guaranteed-simple polygon should pass
* a smaller epsilon (or 0) until a topology-preserving variant exists.
*
* @param IntArray points Flattened x0, y0, x1, y1, ... closed ring; last point connects to the first.
* @param Float epsilon Maximum allowed deviation from the input ring, in pixels; non-negative.
* @return IntArray The simplified ring, or the input array itself when nothing can be dropped.
*/
internal fun simplifyClosedRing(points: IntArray, epsilon: Float): IntArray {
val pointCount = points.size / 2
if (pointCount < 4) {
// A triangle is already minimal: dropping any vertex would degenerate the ring.
return points
}
var anchorB = 0
var anchorBSquaredDistance = -1L
for (pointIndex in 1 until pointCount) {
val deltaX = (points[pointIndex * 2] - points[0]).toLong()
val deltaY = (points[pointIndex * 2 + 1] - points[1]).toLong()
val squaredDistance = deltaX * deltaX + deltaY * deltaY
if (squaredDistance > anchorBSquaredDistance) {
anchorBSquaredDistance = squaredDistance
anchorB = pointIndex
}
}
val keep = BooleanArray(pointCount)
keep[0] = true
keep[anchorB] = true
val epsilonSquared = epsilon.toDouble() * epsilon.toDouble()
// Ranges use virtual indices 0..pointCount so the wrap-around half (anchorB back to A) is
// a plain ascending range; a virtual index maps to ring index (virtual % pointCount).
val rangeStack = IntStack()
rangeStack.push(0)
rangeStack.push(anchorB)
rangeStack.push(anchorB)
rangeStack.push(pointCount)
while (rangeStack.isNotEmpty()) {
val lastVirtual = rangeStack.pop()
val firstVirtual = rangeStack.pop()
if (lastVirtual - firstVirtual < 2) {
continue
}
val segmentStartIndex = (firstVirtual % pointCount) * 2
val segmentEndIndex = (lastVirtual % pointCount) * 2
var farthestVirtual = -1
var farthestSquaredDistance = -1.0
for (interiorVirtual in firstVirtual + 1 until lastVirtual) {
val interiorIndex = (interiorVirtual % pointCount) * 2
val squaredDistance =
squaredDistanceToSegment(
pointX = points[interiorIndex],
pointY = points[interiorIndex + 1],
segmentStartX = points[segmentStartIndex],
segmentStartY = points[segmentStartIndex + 1],
segmentEndX = points[segmentEndIndex],
segmentEndY = points[segmentEndIndex + 1],
)
if (squaredDistance > farthestSquaredDistance) {
farthestSquaredDistance = squaredDistance
farthestVirtual = interiorVirtual
}
}
if (farthestSquaredDistance > epsilonSquared) {
keep[farthestVirtual % pointCount] = true
rangeStack.push(firstVirtual)
rangeStack.push(farthestVirtual)
rangeStack.push(farthestVirtual)
rangeStack.push(lastVirtual)
}
}
var keptCount = 0
for (pointIndex in 0 until pointCount) {
if (keep[pointIndex]) {
keptCount++
}
}
if (keptCount < 3) {
return points
}
if (keptCount == pointCount) {
return points
}
val simplified = IntArray(keptCount * 2)
var writeIndex = 0
for (pointIndex in 0 until pointCount) {
if (keep[pointIndex]) {
simplified[writeIndex] = points[pointIndex * 2]
simplified[writeIndex + 1] = points[pointIndex * 2 + 1]
writeIndex += 2
}
}
return simplified
}
/**
* Squared distance from a point to a segment, clamped to the segment's endpoints.
*
* Dot, cross, and length products are exact Longs from Int coordinates; only the final
* quotient goes through Double. A zero-length segment (possible between weakly simple ring
* vertices that coincide) degrades to point distance.
*
* @param Int pointX The point's x.
* @param Int pointY The point's y.
* @param Int segmentStartX Segment start x.
* @param Int segmentStartY Segment start y.
* @param Int segmentEndX Segment end x.
* @param Int segmentEndY Segment end y.
* @return Double The squared distance in pixels squared.
*/
private fun squaredDistanceToSegment(
pointX: Int,
pointY: Int,
segmentStartX: Int,
segmentStartY: Int,
segmentEndX: Int,
segmentEndY: Int,
): Double {
val segmentDeltaX = (segmentEndX - segmentStartX).toLong()
val segmentDeltaY = (segmentEndY - segmentStartY).toLong()
val toPointX = (pointX - segmentStartX).toLong()
val toPointY = (pointY - segmentStartY).toLong()
val segmentLengthSquared = segmentDeltaX * segmentDeltaX + segmentDeltaY * segmentDeltaY
if (segmentLengthSquared == 0L) {
return (toPointX * toPointX + toPointY * toPointY).toDouble()
}
val projection = toPointX * segmentDeltaX + toPointY * segmentDeltaY
if (projection <= 0L) {
return (toPointX * toPointX + toPointY * toPointY).toDouble()
}
if (projection >= segmentLengthSquared) {
val fromEndX = (pointX - segmentEndX).toLong()
val fromEndY = (pointY - segmentEndY).toLong()
return (fromEndX * fromEndX + fromEndY * fromEndY).toDouble()
}
val cross = toPointX * segmentDeltaY - toPointY * segmentDeltaX
return cross.toDouble() * cross.toDouble() / segmentLengthSquared.toDouble()
}
@@ -0,0 +1,336 @@
package org.umamo.format.art
import org.umamo.format.FormatCodec
import org.umamo.format.ReadOnlyCodec
import kotlin.jvm.JvmInline
/**
* Stable identity of a source-art layer, format-agnostic.
*
* `@JvmInline value class` wraps a String with zero runtime overhead (the compiler erases it
* to a bare String where it can) while making the type distinct - you can't accidentally pass a
* raw layer name where a layer id is expected. This replaces the "stringly-typed" anti-pattern
* (`Map<String, …>` keyed by ambiguous strings). The meaning of the wrapped value depends on
* the source: CLIP supplies Celsys's rename-stable internal id; PSD can only offer a name/path.
*
* The `kotlin.jvm.JvmInline` import is load-bearing, not noise: `kotlin.jvm.*` is a default import
* only on JVM targets, so without it this file stops compiling the moment a non-JVM target
* (Kotlin/Native, for iPadOS) is added. The annotation is an optional expectation, so non-JVM
* targets simply ignore it.
*
* ソースレイヤーの安定 ID。value class で型安全かつゼロコスト。
*/
@JvmInline
value class LayerId(val raw: String)
/**
* Position and size of a layer on the source canvas, in pixels, with a top-left origin (the
* image/PSD convention). The renderer flips Y when mapping to GL's bottom-left origin.
* [AlphaAnalysis.opaqueBounds] reuses this shape raster-locally, with left/top relative to the
* raster's own origin instead of the canvas.
*/
data class LayerBounds(
val left: Int,
val top: Int,
val width: Int,
val height: Int,
) {
/** The rectangle's area in pixels; zero for an empty one. */
val area: Long get() = if (width <= 0 || height <= 0) 0L else width.toLong() * height.toLong()
/**
* How much of the union of this rectangle and [other] both cover: 1 for the same rectangle, 0 for
* disjoint ones - the overlap measure a layer matcher scores a candidate's placement on.
*
* @param LayerBounds other The other rectangle.
* @return Float The intersection over the union, 0 when either rectangle is empty.
*/
fun intersectionOverUnion(other: LayerBounds): Float {
if (area == 0L || other.area == 0L) {
return 0f
}
val overlapWidth = minOf(left + width, other.left + other.width) - maxOf(left, other.left)
val overlapHeight = minOf(top + height, other.top + other.height) - maxOf(top, other.top)
if (overlapWidth <= 0 || overlapHeight <= 0) {
return 0f
}
val intersection = overlapWidth.toLong() * overlapHeight.toLong()
return intersection.toFloat() / (area + other.area - intersection).toFloat()
}
}
/**
* How a layer composites onto what's beneath it - the full PSD/Clip Studio/Krita blend-mode set.
*
* Source art (PSD, CLIP, KRA) shares essentially the same blend-mode vocabulary, so the neutral
* model carries it verbatim rather than collapsing it. A renderer that only supports a subset
* (Cubism drawables are Normal/Add/Multiply) maps the rest down at draw time - that is a render
* concern, not a reason to discard the source's intent here. Defaults to [Normal] (source-over).
* CSP-specific names noted: [GlowDodge] and [AddGlow] are CSP's clamped Color-Dodge/Add variants;
* [Luminosity] is CSP's "Brightness".
*/
enum class LayerBlend {
Normal,
Darken,
Multiply,
ColorBurn,
LinearBurn,
Subtract,
DarkerColor,
Lighten,
Screen,
ColorDodge,
GlowDodge,
Add,
AddGlow,
LighterColor,
Overlay,
SoftLight,
HardLight,
VividLight,
LinearLight,
PinLight,
HardMix,
Difference,
Exclusion,
Hue,
Saturation,
Color,
Luminosity,
Divide,
}
/**
* What kind of source layer this is - chiefly, whether it carries ingestible raster pixels.
*
* EN: A raster-ingesting consumer cares most about [Raster] (has decodable pixels) versus everything
* else (no stored raster). The non-raster kinds are still surfaced so a consumer can report or
* skip them knowingly rather than treating them as empty raster layers: [Text] and [Vector] are
* object layers whose content is regenerated from object data on load (no persisted raster);
* [Adjustment] is a procedural correction/filter layer; [Fill] is a paper/solid-fill layer.
* JA: レイヤー種別。取り込み側はラスタの有無を知る必要がある。非ラスタ種別も識別して通知/スキップできる。
*/
enum class SourceLayerKind {
Raster,
Text,
Vector,
Adjustment,
Fill,
Unknown,
}
/**
* Which of the four output channels a layer writes when composited; a disabled channel passes
* through from the content below instead of being written by this layer. Defaults to all enabled,
* since most sources do not expose per-channel masking. Krita's channelflags populates this; a
* disabled alpha is the same underlying signal as inherit-alpha clipping (see SourceLayer.clipped).
*
* レイヤーが合成時に書き込むチャンネル。無効なチャンネルは下のレイヤーを通す。既定は全て有効。
*/
data class ChannelMask(
val red: Boolean,
val green: Boolean,
val blue: Boolean,
val alpha: Boolean,
) {
companion object {
/** All channels enabled - the default when a source exposes no per-channel masking. */
val ALL: ChannelMask = ChannelMask(red = true, green = true, blue = true, alpha = true)
}
}
/**
* Decoded pixels for one layer: RGBA8888, straight (non-premultiplied) alpha, row-major from
* the top, sized to the layer's cropped [bounds][SourceLayer.bounds] (not the full canvas).
*
* A plain class, not a `data class`: it wraps a large [rgba] buffer for which generated structural
* equals/hashCode would be a footgun (a deep array compare on every call). Identity equality is the
* right default here.
*
* レイヤーの復号済みピクセル(RGBA8888・ストレートアルファ・上から行優先)。
*/
class LayerRaster(
val width: Int,
val height: Int,
val rgba: ByteArray,
)
/**
* Whether every pixel of this raster is fully transparent - a layer the artist erased to nothing, as
* opposed to one that merely fell under an import's alpha threshold.
*
* @return Boolean True when no pixel has any alpha.
*/
fun LayerRaster.isFullyTransparent(): Boolean {
var offset = 3
while (offset < rgba.size) {
if (rgba[offset].toInt() != 0) {
return false
}
offset += 4
}
return true
}
/**
* One layer of ingested source art, neutral across PSD/CLIP/KRA. [id] is the re-import join key;
* [groupPath] is the slash-joined group hierarchy used as the PSD fallback key when [id] is weak.
*/
interface SourceLayer {
val id: LayerId
val name: String
val groupPath: String
/**
* What kind of layer this is. Defaults to [SourceLayerKind.Raster] - the common case and the only
* kind the PSD/KRA readers emit - so only readers that surface non-raster layers (CLIP) override
* it. A raster-only consumer ingests [SourceLayerKind.Raster] and skips the rest.
*/
val kind: SourceLayerKind get() = SourceLayerKind.Raster
/**
* Whether this layer is shown (the eye toggle). Defaults to true. A hidden layer is still read and
* surfaced so the consumer can decide whether to ingest or skip it; a layer can also be effectively
* hidden by an ancestor folder being hidden ([SourceGroup.visible]).
*/
val visible: Boolean get() = true
/**
* Whether [id] is a format-minted identity that survives a rename or reorder in the art program (a
* CLIP or Krita layer uuid, a PSD lyid), as opposed to a name-and-order fallback that holds only as
* long as the artist's layer organization does. Defaults to true because every reader mints a
* stable id wherever the format offers one; a reader overrides it to false for the layers where it
* had to fall back. The re-import join trusts a stable key outright and routes the rest through
* review.
*/
val idIsStable: Boolean get() = true
/** Draw order within the source document (top-most first), used to disambiguate fallbacks. */
val order: Int
/** Where this layer sits on the source canvas. */
val bounds: LayerBounds
/** Layer opacity, 0.0..1.0 (PSD stores 0..255). */
val opacity: Float
/**
* True if this is a clipping-mask layer: its output is clipped to the alpha of the first
* non-clipped ("base") layer below it in the same group (Photoshop "clip to layer below").
*/
val clipped: Boolean
/** Compositing mode against the layers beneath. */
val blend: LayerBlend
/**
* Which output channels this layer contributes; a disabled channel passes through from below.
* Defaults to all enabled, as most sources do not expose per-channel masking.
*/
val channelMask: ChannelMask get() = ChannelMask.ALL
/** Decoded pixels, cropped to [bounds]. */
val raster: LayerRaster
}
/**
* A folder/group in the source-art hierarchy, identified by its slash-joined [path] (the same path
* the enclosed [SourceLayer]s carry in [SourceLayer.groupPath]).
*
* The flat model keys layers to their enclosing folders by path string rather than nesting; this
* carries the per-folder attributes that a flattened leaf list would otherwise lose - chiefly the
* folder [blend] and [opacity], which composite the whole group and are not equivalent to setting
* each child layer's blend. [passThrough] marks a folder that does not isolate (CSP "Through"): its
* children blend straight onto what is below the folder, so [blend] is moot.
*
* フォルダ属性(パスで識別)。フォルダのブレンド/不透明度は平坦化で失われるためここで保持する。
*/
interface SourceGroup {
/** Slash-joined path identifying this folder, matching enclosed layers' [SourceLayer.groupPath]. */
val path: String
val name: String
/** Whether the folder is shown; a hidden folder hides its whole subtree. */
val visible: Boolean
/** Folder opacity, 0.0..1.0. */
val opacity: Float
/** True if the folder itself is a clipping layer (clips to the layer below it). */
val clipped: Boolean
/** How the folder composites onto what is beneath it (ignored when [passThrough] is true). */
val blend: LayerBlend
/**
* True for a non-isolating "pass-through" folder (Clip Studio's default folder mode): the group's
* children composite directly against the layers below the folder rather than within an isolated
* group buffer. When true, [blend] does not apply.
*/
val passThrough: Boolean
}
/**
* A parsed source-art document: an ordered set of [SourceLayer]s, the [SourceGroup]s describing the
* folders that enclose them (keyed by path), plus the document pixel bounds.
*
* [groups] defaults to empty so readers that flatten without folder metadata (PSD, KRA) need no
* change; CLIP overrides it.
*/
interface SourceArt {
val layers: List<SourceLayer>
val groups: List<SourceGroup> get() = emptyList()
val widthPx: Int
val heightPx: Int
}
/**
* Effective on-screen visibility of [layer]: its own eye toggle folded together with every ancestor
* folder's. A layer is shown only when it is itself visible and none of the folders enclosing it is
* hidden; the enclosing folders are found by walking [SourceLayer.groupPath] upward (a layer in
* "A/B/C" is hidden if any of "A", "A/B", or "A/B/C" is hidden). With no [groups] - the flat PSD/KRA
* case, or a document with no folders - this reduces to [SourceLayer.visible].
*
* This is the pre-flattened answer for consumers that have no folder hierarchy of their own - the
* source-art preview compositor, which just draws a flat layer list. It is deliberately NOT what the
* eventual SourceArt to puppet-model ingest should use: that path keeps the two flags separate
* (each layer's own [SourceLayer.visible] seeds its drawable's eye toggle, each folder's
* [SourceGroup.visible] seeds the part the folder becomes) and lets the runtime's part-chain
* visibility cascade hide a still-"visible" layer whose ancestor part is hidden. Flattening here
* would discard the per-layer intent the artist may want back when they re-show a folder. Use this
* for "should I draw this now", not for "what is this layer's stored visibility".
*
* @param SourceLayer layer The layer to test; its [SourceLayer.groupPath] locates its folders.
* @return Boolean Whether the layer should be drawn by a flat (folderless) consumer.
*/
fun SourceArt.isEffectivelyVisible(layer: SourceLayer): Boolean {
if (!layer.visible) {
return false
}
if (groups.isEmpty() || layer.groupPath.isEmpty()) {
return true
}
val groupByPath = groups.associateBy { group -> group.path }
var ancestorPath = layer.groupPath
while (ancestorPath.isNotEmpty()) {
val ancestor = groupByPath[ancestorPath]
if (ancestor != null && !ancestor.visible) {
return false
}
val lastSlash = ancestorPath.lastIndexOf('/')
ancestorPath = if (lastSlash < 0) "" else ancestorPath.substring(0, lastSlash)
}
return true
}
/**
* A [FormatCodec] whose in-memory model is the neutral [SourceArt] - one implementation per art
* format (PSD, CLIP, KRA). Folding the art readers into [FormatCodec] lets the format registry
* detect and resolve them exactly like the binary model codecs (CMO3/MOC3), rather than through a
* separate reader facade. These formats are ingestion-only, so [ReadOnlyCodec] supplies the
* refusing write - and every art FileKind has writable = false, which advertises that to callers
* before they try.
*
* ソースアートを読む FormatCodec。形式ごとに実装。読み取り専用なので write は常に拒否する。
*/
interface ArtReader : ReadOnlyCodec<SourceArt>
@@ -0,0 +1,601 @@
package org.umamo.format.atlas
import org.umamo.format.art.DEFAULT_ALPHA_THRESHOLD
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.LayerRaster
import org.umamo.format.art.SourceArt
import org.umamo.format.art.SourceLayer
import org.umamo.format.art.analyzeAlpha
import org.umamo.format.raster.RasterImage
import kotlin.math.ceil
import kotlin.math.floor
/*
* The atlas packer: source-layer rasters in, packed pages plus a placement report out.
*
* Because the 2D source art hands us each piece's opaque silhouette before packing, the atlas can
* be generated rather than authored by hand and reconciled. The packing REPORT is deliberately
* not a placement transform: it records integer page rectangles, the trim each tile came from, and
* the quarter turn applied, which is what a packer knows. Lowering that onto a placement transform
* belongs with whoever owns the placement model.
*
* Its own package rather than sitting beside analyzeAlpha in `art`, because the packer reads layers
* and writes flat images: `art` deliberately does not depend on `raster` (see RasterImage's
* analyzeAlpha extension), and this is the node that legitimately spans both.
*/
/**
* Extra area a tile's placement must keep clear, in raster-local pixels.
*
* The pixels alone do not bound what samples a tile: an art mesh rings OUTSIDE the opaque region
* (and routinely outside the raster itself), so a pack spaced by opaque bounds alone puts one
* tile's mesh footprint over its neighbor's art. A reserve carries that reach into the pack: the
* tile's reservation becomes the union of its opaque trim and this rect, so anything inside it
* lands on the tile's own transparent margin rather than on a neighbor.
*
* Coordinates are raster-local like a trim's, edges exclusive on the right and bottom, and MAY be
* negative or exceed the raster - a mesh's reach is not confined to its art.
*
* @property Int left The reserved rect's left edge.
* @property Int top The reserved rect's top edge.
* @property Int right The reserved rect's right edge, exclusive.
* @property Int bottom The reserved rect's bottom edge, exclusive.
*/
public data class AtlasPackReserve(
val left: Int,
val top: Int,
val right: Int,
val bottom: Int,
) {
init {
require(right >= left && bottom >= top) { "reserve must not be inverted: $left..$right x $top..$bottom" }
}
}
/**
* A place on a page decided BEFORE the pack: the tile stays exactly here, and the free tiles pack
* around it. This is what a pinned placement is to a repack.
*
* Expressed as the tile's full tile-to-page affine rather than a rect, because a hand placement may
* be rotated, scaled, or off the pixel grid - none of which an [AtlasPackPlacement] can hold - and
* the tile is painted through that same affine, by the same path a derivation paints it, so the
* packed page and a page derived from the kept placement cannot differ.
*
* @property Int pageIndex The page the tile stays on.
* @property FloatArray tileToPage The affine (m00, m01, m02, m10, m11, m12) mapping tile pixels to
* page pixels, both frames y-down - [AtlasTilePlacement]'s convention.
*/
public class AtlasPackFixed(
public val pageIndex: Int,
public val tileToPage: FloatArray,
) {
init {
require(pageIndex >= 0) { "fixed page index must not be negative: $pageIndex" }
require(tileToPage.size == 6) { "a fixed placement needs a 2x3 affine, got ${tileToPage.size} components" }
}
}
/**
* One tile to pack: a stable key plus the straight-alpha pixels to place.
*
* Pixels are taken by reference and never mutated, matching how the flat-raster adapter hands a
* buffer through; the caller must not mutate [rgba] while a pack is running.
*
* A plain class, not a data class: it wraps a pixel buffer whose generated structural equality would
* deep-compare on every call, the same reason [LayerRaster] and [RasterImage] are plain classes.
*
* @property String key The tile's stable identity, unique within one pack.
* @property Int width The raster width in pixels.
* @property Int height The raster height in pixels.
* @property ByteArray rgba RGBA8888 pixels, straight alpha, row-major from the top row.
* @property AtlasPackReserve? reserve Extra area to keep clear around this tile (a mesh's reach),
* unioned with the opaque trim; null reserves the trim alone.
* @property AtlasPackFixed? fixed Where the tile already sits and stays, or null to let the
* packer place it.
*/
public class AtlasPackItem(
public val key: String,
public val width: Int,
public val height: Int,
public val rgba: ByteArray,
public val reserve: AtlasPackReserve? = null,
public val fixed: AtlasPackFixed? = null,
) {
init {
require(width >= 0 && height >= 0) { "tile '$key' has negative dimensions: $width x $height" }
require(rgba.size.toLong() == width.toLong() * height.toLong() * 4L) {
"tile '$key' rgba size ${rgba.size} does not match $width x $height x 4"
}
}
}
/**
* How to pack.
*
* @property Int maxPageSize The square page side pages are packed against, in pixels.
* @property Int gutter Transparent spacing reserved around every tile and at the page border.
* @property Int extrude How many pixels of gutter around each tile carry its edge color, at zero alpha.
* @property Boolean allowRotation Whether a tile may be quarter-turned to pack tighter.
* @property Boolean powerOfTwoPages Whether final page dimensions round up to a power of two.
* @property Boolean squarePages Whether final pages are square, as every corpus atlas is.
* @property Boolean shrinkPages Whether pages size themselves to the document instead of staying at [maxPageSize].
* @property Int alphaThreshold Minimum alpha byte (1..255) for a pixel to count as opaque when trimming.
* @property Int minimumOpaquePixels Tiles with fewer opaque pixels than this are reported rather than packed.
*/
public data class AtlasPackOptions(
val maxPageSize: Int = 4096,
val gutter: Int = 2,
val extrude: Int = 2,
val allowRotation: Boolean = false,
val powerOfTwoPages: Boolean = true,
val squarePages: Boolean = true,
val shrinkPages: Boolean = true,
val alphaThreshold: Int = DEFAULT_ALPHA_THRESHOLD,
val minimumOpaquePixels: Int = 1,
)
/**
* Where one tile landed, in whole page pixels.
*
* [pageX] / [pageY] locate the tile itself, not its gutter footprint. The trim fields say which part
* of the source raster was packed: a tile is trimmed to its opaque bounds, so the source pixel
* (trimLeft + tileX, trimTop + tileY) is what sits at the placed position. A [quarterTurns] of 1
* means the tile was rotated one counter-clockwise quarter turn in the page's y-down frame, which
* swaps its on-page width and height.
*
* @property String key The packed tile's key.
* @property Int pageIndex The page it landed on.
* @property Int pageX The tile's left edge on the page.
* @property Int pageY The tile's top edge on the page.
* @property Int trimLeft The opaque bounds' left edge within the source raster.
* @property Int trimTop The opaque bounds' top edge within the source raster.
* @property Int trimWidth The opaque bounds' width, before any rotation.
* @property Int trimHeight The opaque bounds' height, before any rotation.
* @property Int quarterTurns 0 for upright, 1 for one counter-clockwise quarter turn.
*/
public data class AtlasPackPlacement(
val key: String,
val pageIndex: Int,
val pageX: Int,
val pageY: Int,
val trimLeft: Int,
val trimTop: Int,
val trimWidth: Int,
val trimHeight: Int,
val quarterTurns: Int,
) {
/** The tile's width on the page, after any quarter turn. */
public val pageWidth: Int
get() = if (quarterTurns == 0) trimWidth else trimHeight
/** The tile's height on the page, after any quarter turn. */
public val pageHeight: Int
get() = if (quarterTurns == 0) trimHeight else trimWidth
}
/** Why a tile was not packed. */
public enum class AtlasPackSkipReason {
/** Nothing in the raster met the alpha threshold - an empty layer, or a transparent placeholder. */
NoOpaquePixels,
/** The tile has opaque pixels but fewer than the configured minimum. */
BelowMinimumCoverage,
/** The trimmed tile plus its gutter does not fit a page even on its own. */
LargerThanPage,
/**
* The tile is fixed at a spot that does not fit inside the largest page the pack may use - its
* opaque art runs past the right or bottom edge. Reserve and gutter alone spilling past the edge
* do not refuse: they are clamped, the way a free pack's page-border gutter is.
*/
FixedOutsidePage,
}
/**
* One tile that was not packed, and why.
*
* @property String key The tile's key.
* @property AtlasPackSkipReason reason Why it was left out.
*/
public data class AtlasPackSkip(
val key: String,
val reason: AtlasPackSkipReason,
)
/**
* One fixed tile the pack kept where it was: the page it stayed on, the trim it painted there, and
* the affine it painted through.
*
* A plain class: [tileToPage] is an array.
*
* @property String key The tile's key.
* @property Int pageIndex The page it stayed on.
* @property Int trimLeft The opaque bounds' left edge within the source raster.
* @property Int trimTop The opaque bounds' top edge within the source raster.
* @property Int trimWidth The opaque bounds' width.
* @property Int trimHeight The opaque bounds' height.
* @property FloatArray tileToPage The affine it was painted through, as the caller gave it.
*/
public class AtlasPackFixedPlacement(
public val key: String,
public val pageIndex: Int,
public val trimLeft: Int,
public val trimTop: Int,
public val trimWidth: Int,
public val trimHeight: Int,
public val tileToPage: FloatArray,
)
/**
* The packing outcome: the composed pages plus a full account of every tile that went in.
*
* [placements], [fixed], and [skipped] partition the input keys exactly - every tile handed to
* [packAtlas] appears in one of them. That is the contract that keeps a plausible-looking page from
* quietly having lost three layers, which is this stage's characteristic failure.
*
* A plain class, not a data class: [pages] holds pixel buffers.
*
* @property List pages The composed atlas pages, in page-index order.
* @property List placements Where each packed tile landed, in the caller's input order.
* @property List skipped The tiles left out, in the caller's input order.
* @property List fixed The tiles kept where they were, in the caller's input order.
*/
public class AtlasPackResult(
public val pages: List<RasterImage>,
public val placements: List<AtlasPackPlacement>,
public val skipped: List<AtlasPackSkip>,
public val fixed: List<AtlasPackFixedPlacement> = emptyList(),
) {
/**
* The fraction of a page's area covered by tile pixels, ignoring gutters and extrusion. A packed
* tile covers its trim; a fixed tile covers its trim through its affine's area scale.
*
* @param Int pageIndex The page to measure.
* @return Float The covered fraction, in 0.0..1.0.
*/
public fun pageOccupancy(pageIndex: Int): Float {
val page = pages[pageIndex]
var covered = 0.0
for (placement in placements) {
if (placement.pageIndex == pageIndex) {
covered += placement.trimWidth.toDouble() * placement.trimHeight.toDouble()
}
}
for (kept in fixed) {
if (kept.pageIndex == pageIndex) {
val affine = kept.tileToPage
val areaScale = kotlin.math.abs(affine[0] * affine[4] - affine[1] * affine[3])
covered += kept.trimWidth.toDouble() * kept.trimHeight.toDouble() * areaScale
}
}
return (covered / (page.width.toDouble() * page.height.toDouble())).toFloat()
}
}
/**
* A fixed tile's page footprint before the pack decides a page side: its trim widened by its reserve,
* through its affine, rounded out to pixels and grown by the gutter on every side.
*
* @property Int itemIndex The fixed item.
* @property Int pageIndex The page it stays on.
* @property Int left The footprint's left edge, gutter included, clamped to the page.
* @property Int top The footprint's top edge, gutter included, clamped to the page.
* @property Int right The footprint's right edge, exclusive, gutter included, clamped to the page.
* @property Int bottom The footprint's bottom edge, exclusive, gutter included, clamped to the page.
* @property Int artRight The opaque art's right edge, exclusive - what decides whether the tile fits.
* @property Int artBottom The opaque art's bottom edge, exclusive.
*/
private class FixedFootprint(
val itemIndex: Int,
val pageIndex: Int,
val left: Int,
val top: Int,
val right: Int,
val bottom: Int,
val artRight: Int,
val artBottom: Int,
) {
/** The footprint as the rect packer's seed. */
fun toSeed(): RectPackSeed = RectPackSeed(pageIndex, left, top, right - left, bottom - top)
}
/**
* Packs tiles into atlas pages and composes the page pixels.
*
* Each tile is trimmed to its opaque bounds (lossless at the default threshold - no antialiased edge
* pixel is cut), reserved with a gutter on every side, placed by the MaxRects packer, blitted, and
* its edge color bled into its gutter at zero alpha. Pages are packed against [AtlasPackOptions.maxPageSize] and then cropped
* to what was used, so a document that needs a 512 page gets one rather than a mostly-empty 4096.
*
* The result is DETERMINISTIC: tiles are ordered by descending max side, then descending area, then
* key, so the caller's input order cannot change the packing. Repacking an unchanged set therefore
* reproduces it exactly, which is what makes a repack a safe operation rather than a churn source.
*
* A tile with an [AtlasPackItem.fixed] placement is not packed at all: its footprint (trim, reserve,
* and gutter, through its affine) seeds its page before any free tile is placed, so the free tiles
* pack around it, and it is painted through its own affine after them. Its page index is kept as
* given, so every page up to it exists even if nothing else lands there (an empty page crops to its
* used extent like any other). A fixed tile whose art does not fit inside [AtlasPackOptions.maxPageSize]
* is reported as [AtlasPackSkipReason.FixedOutsidePage] rather than moved - the caller decided to
* keep it, so the packer never second-guesses where; reserve and gutter that spill past the edge are
* clamped to it, not refused.
*
* @param List items The tiles to pack; keys must be unique.
* @param AtlasPackOptions options The packing policy.
* @return AtlasPackResult The composed pages, the placements, the tiles kept fixed, and the tiles left out.
*/
public fun packAtlas(
items: List<AtlasPackItem>,
options: AtlasPackOptions = AtlasPackOptions(),
): AtlasPackResult {
require(options.maxPageSize > 0) { "maxPageSize must be positive: ${options.maxPageSize}" }
require(options.gutter >= 0) { "gutter must be non-negative: ${options.gutter}" }
require(options.extrude in 0..options.gutter) {
"extrude must be in 0..gutter (${options.gutter}) so no tile's extrusion reaches another: ${options.extrude}"
}
require(options.alphaThreshold in 1..255) { "alphaThreshold must be in 1..255: ${options.alphaThreshold}" }
require(options.minimumOpaquePixels >= 0) {
"minimumOpaquePixels must be non-negative: ${options.minimumOpaquePixels}"
}
require(items.distinctBy { item -> item.key }.size == items.size) {
"atlas pack item keys must be unique; duplicates make the packing order ambiguous"
}
// Trim first: a tile's footprint is its opaque bounds - widened to any caller reserve, since a
// mesh's reach must land on the tile's own margin - plus the gutter, and a tile with nothing
// opaque never reaches the packer at all. A fixed tile's footprint goes through its affine
// instead of into a request.
val trims = arrayOfNulls<LayerBounds>(items.size)
val reserves = arrayOfNulls<LayerBounds>(items.size)
val skipped = ArrayList<AtlasPackSkip>()
val requests = ArrayList<RectPackRequest>(items.size)
val fixedFootprints = ArrayList<FixedFootprint>()
for ((itemIndex, item) in items.withIndex()) {
val analysis = analyzeAlpha(item.width, item.height, item.rgba, options.alphaThreshold)
if (analysis == null) {
skipped.add(AtlasPackSkip(item.key, AtlasPackSkipReason.NoOpaquePixels))
continue
}
if (analysis.opaquePixelCount < options.minimumOpaquePixels) {
skipped.add(AtlasPackSkip(item.key, AtlasPackSkipReason.BelowMinimumCoverage))
continue
}
val trim = analysis.opaqueBounds
val reserveLeft = minOf(trim.left, item.reserve?.left ?: trim.left)
val reserveTop = minOf(trim.top, item.reserve?.top ?: trim.top)
val reserveRight = maxOf(trim.left + trim.width, item.reserve?.right ?: (trim.left + trim.width))
val reserveBottom = maxOf(trim.top + trim.height, item.reserve?.bottom ?: (trim.top + trim.height))
trims[itemIndex] = trim
reserves[itemIndex] = LayerBounds(reserveLeft, reserveTop, reserveRight - reserveLeft, reserveBottom - reserveTop)
val fixed = item.fixed
if (fixed != null) {
val bounds = affineBounds(fixed.tileToPage, reserveLeft.toFloat(), reserveTop.toFloat(), reserveRight.toFloat(), reserveBottom.toFloat())
val artBounds =
affineBounds(fixed.tileToPage, trim.left.toFloat(), trim.top.toFloat(), (trim.left + trim.width).toFloat(), (trim.top + trim.height).toFloat())
// An overhang past the top or left is cropped by the composition, so the footprint starts at
// the page edge there. Past the right or bottom, only the ART decides whether the tile fits:
// a reserve or gutter spilling over the edge is clamped to it, exactly as a free pack's own
// page-border gutter is - a tile the free pack placed flush against the edge would otherwise
// be refused as fixed, since its mesh reach re-measured from page coordinates can round a
// pixel wider than the reach it was packed with.
fixedFootprints.add(
FixedFootprint(
itemIndex = itemIndex,
pageIndex = fixed.pageIndex,
left = floor(bounds[0] - options.gutter).toInt().coerceAtLeast(0),
top = floor(bounds[1] - options.gutter).toInt().coerceAtLeast(0),
right = ceil(bounds[2] + options.gutter).toInt().coerceIn(0, options.maxPageSize),
bottom = ceil(bounds[3] + options.gutter).toInt().coerceIn(0, options.maxPageSize),
artRight = ceil(artBounds[2]).toInt().coerceAtLeast(0),
artBottom = ceil(artBounds[3]).toInt().coerceAtLeast(0),
),
)
continue
}
requests.add(
RectPackRequest(
itemIndex = itemIndex,
width = reserveRight - reserveLeft + 2 * options.gutter,
height = reserveBottom - reserveTop + 2 * options.gutter,
),
)
}
requests.sortWith(
compareByDescending<RectPackRequest> { request -> maxOf(request.width, request.height) }
.thenByDescending { request -> request.width.toLong() * request.height.toLong() }
.thenBy { request -> items[request.itemIndex].key },
)
// A fixed tile whose ART runs past the largest page can never be kept; every other one seeds each
// trial pack, so the side the pack settles on always holds them all.
val keptFootprints = ArrayList<FixedFootprint>(fixedFootprints.size)
for (footprint in fixedFootprints) {
if (footprint.artRight > options.maxPageSize || footprint.artBottom > options.maxPageSize) {
skipped.add(AtlasPackSkip(items[footprint.itemIndex].key, AtlasPackSkipReason.FixedOutsidePage))
} else {
keptFootprints.add(footprint)
}
}
val seeds = keptFootprints.map { footprint -> footprint.toSeed() }
val packingSide = choosePackingSide(requests, seeds, options)
val layout = packRects(requests, packingSide, options.allowRotation, seeds)
for (itemIndex in layout.oversizedItemIndices) {
skipped.add(AtlasPackSkip(items[itemIndex].key, AtlasPackSkipReason.LargerThanPage))
}
val pageWidths = IntArray(layout.usedWidths.size)
val pageHeights = IntArray(layout.usedHeights.size)
for (pageIndex in layout.usedWidths.indices) {
val sizes = finalPageSize(layout.usedWidths[pageIndex], layout.usedHeights[pageIndex], packingSide, options)
pageWidths[pageIndex] = sizes.first
pageHeights[pageIndex] = sizes.second
}
val placementByItemIndex = arrayOfNulls<AtlasPackPlacement>(items.size)
for (slot in layout.slots) {
val item = items[slot.itemIndex]
val trim = checkNotNull(trims[slot.itemIndex]) { "packed tile '${item.key}' has no trim" }
val reserve = checkNotNull(reserves[slot.itemIndex]) { "packed tile '${item.key}' has no reserve" }
// The placement records the TRIM's page position, not the reservation's: the reservation only
// spaces neighbors further apart, so everything downstream of the placement (the lowering, the
// composition, the derivation) never sees it. A turned slot turns the reservation with the
// tile - the same counter-clockwise quarter turn the blit applies, reserve-local (u, v) landing
// at (v, reserveWidth - u) - so the trim's offset inside it turns too: what sat to the trim's
// LEFT in tile space sits BELOW it on the page.
val trimOffsetX = trim.left - reserve.left
val trimOffsetY = trim.top - reserve.top
val placedOffsetX = if (slot.rotated) trimOffsetY else trimOffsetX
val placedOffsetY = if (slot.rotated) reserve.width - trimOffsetX - trim.width else trimOffsetY
placementByItemIndex[slot.itemIndex] =
AtlasPackPlacement(
key = item.key,
pageIndex = slot.pageIndex,
pageX = slot.x + options.gutter + placedOffsetX,
pageY = slot.y + options.gutter + placedOffsetY,
trimLeft = trim.left,
trimTop = trim.top,
trimWidth = trim.width,
trimHeight = trim.height,
quarterTurns = if (slot.rotated) 1 else 0,
)
}
val placements = placementByItemIndex.filterNotNull()
// The free tiles compose through the packer's blit; the fixed tiles then paint over the same
// buffers in input order through the affine painter, exactly as a derivation paints them.
val pages = composeAtlasPages(pageWidths, pageHeights, items, placements, options.extrude)
val fixedPlacements = ArrayList<AtlasPackFixedPlacement>(keptFootprints.size)
for (footprint in keptFootprints) {
val item = items[footprint.itemIndex]
val fixed = checkNotNull(item.fixed) { "fixed tile '${item.key}' lost its placement" }
val trim = checkNotNull(trims[footprint.itemIndex]) { "fixed tile '${item.key}' has no trim" }
val page = pages[footprint.pageIndex]
paintTilePlacement(page.rgba, page.width, page.height, item, trim, fixed.tileToPage, options.extrude)
fixedPlacements.add(AtlasPackFixedPlacement(item.key, footprint.pageIndex, trim.left, trim.top, trim.width, trim.height, fixed.tileToPage))
}
val inputOrderByKey = items.withIndex().associate { (itemIndex, item) -> item.key to itemIndex }
return AtlasPackResult(
pages = pages,
placements = placements,
skipped = skipped.sortedBy { skip -> inputOrderByKey.getValue(skip.key) },
fixed = fixedPlacements,
)
}
/**
* Builds pack items from this document's layers, one per layer, keyed by its stable layer id.
*
* Layer kind, visibility, and sliver policy are deliberately the caller's: alpha-shape analysis never
* drops a real art layer and leaves the consumer to decide what to ingest, and the same rule applies
* here. Pass [include] to apply a policy; the default packs every layer.
*
* A duplicate layer id (possible from the PSD name-and-order fallback, where no lyid is written) is
* disambiguated with the layer's draw order rather than rejected, since the collision is an artifact
* of a weak source key and not a caller mistake.
*
* @param Function include Which layers to pack; defaults to all of them.
* @return List One pack item per included layer, in document draw order.
*/
public fun SourceArt.atlasPackItems(include: (SourceLayer) -> Boolean = { true }): List<AtlasPackItem> {
val usedKeys = HashSet<String>()
return layers.filter(include).map { layer ->
var key = layer.id.raw
if (!usedKeys.add(key)) {
key = "${layer.id.raw}#${layer.order}"
usedKeys.add(key)
}
AtlasPackItem(key, layer.raster.width, layer.raster.height, layer.raster.rgba)
}
}
/**
* Chooses the page side to pack against: the smallest one that still needs no extra page.
*
* Packing straight against [AtlasPackOptions.maxPageSize] and cropping afterwards is not enough,
* because best-short-side-fit spreads a small document along the top of a huge page - the crop then
* keeps a wide, shallow extent that squares up almost empty. Packing against a page the document
* roughly fills instead makes it stack, and the page count is the thing worth protecting: a smaller
* page that costs an extra texture bind is a worse trade than a slightly emptier one.
*
* Only the rectangle geometry runs here - no pixels are touched - so the handful of trial packs is
* cheap next to a single page composition.
*
* The seeds bound the side from below: a trial smaller than a seed's far edge could not keep it, so
* the first trial is already large enough for every seed, and each trial seeds the same footprints
* the final pack will.
*
* @param List requests The footprints to be packed.
* @param List seeds The fixed footprints every trial must keep.
* @param AtlasPackOptions options The packing policy.
* @return Int The page side to pack against.
*/
private fun choosePackingSide(
requests: List<RectPackRequest>,
seeds: List<RectPackSeed>,
options: AtlasPackOptions,
): Int {
if (!options.shrinkPages || (requests.isEmpty() && seeds.isEmpty())) {
return options.maxPageSize
}
val baseline = packRects(requests, options.maxPageSize, options.allowRotation, seeds)
val fitting = requests.filter { request -> request.width <= options.maxPageSize && request.height <= options.maxPageSize }
if (fitting.isEmpty() && seeds.isEmpty()) {
return options.maxPageSize
}
val largestRequest = fitting.maxOfOrNull { request -> maxOf(request.width, request.height) } ?: 1
val farthestSeed = seeds.maxOfOrNull { seed -> maxOf(seed.x + seed.width, seed.y + seed.height) } ?: 1
var side = roundUpToPowerOfTwo(maxOf(largestRequest, farthestSeed, 1))
while (side < options.maxPageSize) {
val trial = packRects(requests, side, options.allowRotation, seeds)
if (trial.usedWidths.size <= baseline.usedWidths.size &&
trial.oversizedItemIndices.size == baseline.oversizedItemIndices.size
) {
return side
}
side = side shl 1
}
return options.maxPageSize
}
/**
* Resolves one page's final dimensions from the extent the packer actually used.
*
* @param Int usedWidth The rightmost footprint edge on the page, gutter included.
* @param Int usedHeight The lowest footprint edge on the page, gutter included.
* @param Int packingSide The page side the pack ran against.
* @param AtlasPackOptions options The packing policy.
* @return Pair The page width and height in pixels.
*/
private fun finalPageSize(usedWidth: Int, usedHeight: Int, packingSide: Int, options: AtlasPackOptions): Pair<Int, Int> {
if (!options.shrinkPages) {
return packingSide to packingSide
}
var width = usedWidth
var height = usedHeight
if (options.squarePages) {
width = maxOf(width, height)
height = width
}
if (options.powerOfTwoPages) {
width = roundUpToPowerOfTwo(width)
height = roundUpToPowerOfTwo(height)
}
return minOf(width, packingSide) to minOf(height, packingSide)
}
/**
* Rounds a positive extent up to the next power of two.
*
* @param Int extent The extent in pixels; at least 1.
* @return Int The smallest power of two that is at least [extent].
*/
private fun roundUpToPowerOfTwo(extent: Int): Int {
var size = 1
while (size < extent) {
size = size shl 1
}
return size
}
@@ -0,0 +1,811 @@
package org.umamo.format.atlas
import org.umamo.format.art.LayerBounds
import org.umamo.format.raster.RasterImage
import kotlin.math.abs
import kotlin.math.ceil
import kotlin.math.floor
import kotlin.math.roundToInt
/*
* Pixel composition for the atlas packer: writing one trimmed tile into a page buffer, optionally
* quarter-turned, and bleeding its edge color outward into the surrounding gutter - plus the general
* affine blit a hand-authored placement needs, since a rigger may rotate or scale a tile on the page
* where the packer never would.
*
* The gutter band carries the edge's COLOR at zero alpha, never its coverage. A mesh reaches past the
* art it samples, so anything opaque painted around a tile shows as a fringe wherever its art meets the
* edge of its raster; the band's only job is to give a straight-alpha bilinear filter the edge's color to
* blend toward, so a transparent black neighbor does not darken the edge. Umamo's renderer filters
* premultiplied and never sees the band's color, but a page also leaves in an export, and Cubism's own
* pages carry the same band. Beyond the art the page is transparent, exactly as the source layer is.
*
* Every writer here goes through ONE rule, writeSample: a sample never erases content. A destination
* pixel nobody has painted (alpha 0) takes the sample verbatim, transparent or not - which is what keeps
* the packer's disjoint pages byte-identical, since every pixel it touches is untouched. Over painted
* content a transparent sample is skipped, an opaque one replaces (later placements win), a
* translucent one composites source-over, and a bleed band - synthetic pixels - never beats real
* ones. Hand-authored placements overlap; without the rule a later tile's transparent margin cut a
* box out of the tile beneath it.
*
* Kept apart from the packing geometry so the blit can be read and tested as pixels, which is where
* a packer's silent bugs live - an orientation flipped, an extrusion off by one, a stride computed
* from the wrong width.
*/
/**
* Writes one straight-alpha sample into a page pixel under the content-preserving rule (see the file
* comment).
*
* @param ByteArray page The destination page, RGBA8888 row-major from the top.
* @param Int offset The destination pixel's byte offset.
* @param Int red The sample's red, 0..255.
* @param Int green The sample's green, 0..255.
* @param Int blue The sample's blue, 0..255.
* @param Int alpha The sample's alpha, 0..255.
* @param Boolean synthetic True for a bleed-band sample, which only ever fills untouched page.
*/
private fun writeSample(
page: ByteArray,
offset: Int,
red: Int,
green: Int,
blue: Int,
alpha: Int,
synthetic: Boolean,
) {
val destinationAlpha = page[offset + 3].toInt() and 0xFF
if (destinationAlpha == 0) {
// A bleed band holds no alpha, so an earlier tile's band is told apart from untouched page by its
// color: another band never recolors it, and the gutter keeps the color of the edge it borders.
if (synthetic && (page[offset].toInt() != 0 || page[offset + 1].toInt() != 0 || page[offset + 2].toInt() != 0)) {
return
}
page[offset] = red.toByte()
page[offset + 1] = green.toByte()
page[offset + 2] = blue.toByte()
page[offset + 3] = alpha.toByte()
return
}
if (synthetic || alpha == 0) {
return
}
if (alpha == 255) {
page[offset] = red.toByte()
page[offset + 1] = green.toByte()
page[offset + 2] = blue.toByte()
page[offset + 3] = alpha.toByte()
return
}
// Straight-alpha source-over: the sample sits over the earlier content.
val sourceCoverage = alpha / 255f
val destinationCoverage = destinationAlpha / 255f * (1f - sourceCoverage)
val outCoverage = sourceCoverage + destinationCoverage
page[offset] = compositeChannel(red, page[offset], sourceCoverage, destinationCoverage, outCoverage)
page[offset + 1] = compositeChannel(green, page[offset + 1], sourceCoverage, destinationCoverage, outCoverage)
page[offset + 2] = compositeChannel(blue, page[offset + 2], sourceCoverage, destinationCoverage, outCoverage)
page[offset + 3] = (outCoverage * 255f).roundToInt().coerceIn(0, 255).toByte()
}
/**
* One color channel of a straight-alpha source-over composite.
*
* @param Int source The sample's channel, 0..255.
* @param Byte destination The page's channel byte.
* @param Float sourceCoverage The sample's alpha as coverage.
* @param Float destinationCoverage The page's alpha as coverage, already scaled by the sample's transparency.
* @param Float outCoverage The composite's coverage (the two summed).
* @return Byte The composited channel.
*/
private fun compositeChannel(
source: Int,
destination: Byte,
sourceCoverage: Float,
destinationCoverage: Float,
outCoverage: Float,
): Byte {
val destinationValue = destination.toInt() and 0xFF
val composite = (source * sourceCoverage + destinationValue * destinationCoverage) / outCoverage
return composite.roundToInt().coerceIn(0, 255).toByte()
}
/**
* Writes one source raster pixel into a page pixel under the content-preserving rule.
*
* @param ByteArray page The destination page.
* @param Int destinationOffset The destination pixel's byte offset.
* @param ByteArray source The source raster, RGBA8888.
* @param Int sourceOffset The source pixel's byte offset.
*/
private fun writeSourcePixel(
page: ByteArray,
destinationOffset: Int,
source: ByteArray,
sourceOffset: Int,
) {
writeSample(
page,
destinationOffset,
source[sourceOffset].toInt() and 0xFF,
source[sourceOffset + 1].toInt() and 0xFF,
source[sourceOffset + 2].toInt() and 0xFF,
source[sourceOffset + 3].toInt() and 0xFF,
synthetic = false,
)
}
/**
* Bleeds one source raster pixel's color into a page pixel at zero alpha: a gutter pixel that gives
* filtering the edge's color without adding any coverage, filled only where nothing is painted.
*
* @param ByteArray page The destination page.
* @param Int destinationOffset The destination pixel's byte offset.
* @param ByteArray source The source raster, RGBA8888.
* @param Int sourceOffset The source pixel's byte offset.
*/
private fun bleedSourcePixel(
page: ByteArray,
destinationOffset: Int,
source: ByteArray,
sourceOffset: Int,
) {
writeSample(
page,
destinationOffset,
source[sourceOffset].toInt() and 0xFF,
source[sourceOffset + 1].toInt() and 0xFF,
source[sourceOffset + 2].toInt() and 0xFF,
0,
synthetic = true,
)
}
/**
* The source raster byte offset of the pixel that lands at a placed tile's (column, row), under the
* tile's quarter turn - the reader half of [blitTile], shared with the extrusion so both read the
* same texel.
*
* @param Int sourceWidth The source raster's row stride in pixels.
* @param LayerBounds trim The trimmed sub-rectangle, raster-local.
* @param Int column The placed tile's column (post-rotation frame).
* @param Int row The placed tile's row (post-rotation frame).
* @param Int quarterTurns 0 for upright, 1 for one counter-clockwise quarter turn.
* @return Int The source pixel's byte offset.
*/
private fun sourceOffsetOfPlaced(
sourceWidth: Int,
trim: LayerBounds,
column: Int,
row: Int,
quarterTurns: Int,
): Int =
if (quarterTurns == 0) {
((trim.top + row) * sourceWidth + trim.left + column) * 4
} else {
// A quarter turn sends source (tileX, tileY) to placed (tileY, trimWidth - 1 - tileX).
((trim.top + column) * sourceWidth + trim.left + trim.width - 1 - row) * 4
}
/**
* Copies one trimmed tile into a page buffer under the content-preserving rule.
*
* A quarter turn is COUNTER-CLOCKWISE in the page's y-down frame, matching how a placement records
* rotation: source pixel (tileX, tileY) lands at (destinationX + tileY, destinationY + trimWidth - 1
* - tileX), so the destination footprint is trimHeight wide by trimWidth tall.
*
* @param ByteArray page The destination page, RGBA8888 row-major from the top.
* @param Int pageWidth The page width in pixels.
* @param ByteArray sourceRgba The source raster, RGBA8888 row-major from the top.
* @param Int sourceWidth The source raster's width in pixels (its row stride).
* @param LayerBounds trim The opaque sub-rectangle of the source to copy, raster-local.
* @param Int destinationX The tile's left edge on the page.
* @param Int destinationY The tile's top edge on the page.
* @param Int quarterTurns 0 for upright, 1 for one counter-clockwise quarter turn.
*/
internal fun blitTile(
page: ByteArray,
pageWidth: Int,
sourceRgba: ByteArray,
sourceWidth: Int,
trim: LayerBounds,
destinationX: Int,
destinationY: Int,
quarterTurns: Int,
) {
val placedWidth = if (quarterTurns == 0) trim.width else trim.height
val placedHeight = if (quarterTurns == 0) trim.height else trim.width
for (row in 0 until placedHeight) {
val destinationRowOffset = ((destinationY + row) * pageWidth + destinationX) * 4
for (column in 0 until placedWidth) {
writeSourcePixel(
page,
destinationRowOffset + column * 4,
sourceRgba,
sourceOffsetOfPlaced(sourceWidth, trim, column, row, quarterTurns),
)
}
}
}
/**
* Bleeds a placed tile's edge colors outward into the surrounding gutter, at zero alpha.
*
* Bilinear sampling at a tile's border reads half a texel past it, and the renderer filters straight
* alpha, so the color it finds there tints the edge: transparent black would darken it. The band gives
* it the edge's own color with no coverage, so the page past the art stays as transparent as the layer
* is there - a mesh reaching past its art must not find an opaque copy of the edge. The edge is read
* from the SOURCE raster, not from the page: under the content-preserving rule a tile's transparent
* edge may not have landed on the page at all, and the band must carry the tile's own texel color,
* never whatever another tile left there. The caller guarantees room by reserving a gutter of at least
* [extrude] on every side, so no clamping against the page edge is needed here - and a silent clamp
* would hide exactly the arithmetic mistake this is most likely to make. Band pixels are synthetic:
* they fill unpainted pixels only.
*
* @param ByteArray page The destination page, RGBA8888 row-major from the top.
* @param Int pageWidth The page width in pixels.
* @param ByteArray sourceRgba The source raster, RGBA8888 row-major from the top.
* @param Int sourceWidth The source raster's row stride in pixels.
* @param LayerBounds trim The trimmed sub-rectangle, raster-local.
* @param Int tileX The placed tile's left edge on the page.
* @param Int tileY The placed tile's top edge on the page.
* @param Int quarterTurns 0 for upright, 1 for one counter-clockwise quarter turn.
* @param Int extrude How many pixels of edge color to replicate on every side.
*/
internal fun extrudeTileEdges(
page: ByteArray,
pageWidth: Int,
sourceRgba: ByteArray,
sourceWidth: Int,
trim: LayerBounds,
tileX: Int,
tileY: Int,
quarterTurns: Int,
extrude: Int,
) {
val tileWidth = if (quarterTurns == 0) trim.width else trim.height
val tileHeight = if (quarterTurns == 0) trim.height else trim.width
if (extrude <= 0 || tileWidth <= 0 || tileHeight <= 0) {
return
}
for (rowOffset in -extrude until tileHeight + extrude) {
val clampedRow = rowOffset.coerceIn(0, tileHeight - 1)
val insideVertically = rowOffset == clampedRow
for (columnOffset in -extrude until tileWidth + extrude) {
val clampedColumn = columnOffset.coerceIn(0, tileWidth - 1)
if (insideVertically && columnOffset == clampedColumn) {
continue
}
bleedSourcePixel(
page,
((tileY + rowOffset) * pageWidth + tileX + columnOffset) * 4,
sourceRgba,
sourceOffsetOfPlaced(sourceWidth, trim, clampedColumn, clampedRow, quarterTurns),
)
}
}
}
/**
* Composes atlas pages from already-decided placements.
*
* This is the packer's own composition loop opened to callers that hold placements rather than a
* pack request: [packAtlas] composes through here, and a repack's undo re-derives an earlier page
* set through here, so the two can never drift apart. Placement footprints including their
* extrusion are pairwise disjoint (every placement reserves at least [extrude] of gutter on every
* side, which the bounds checks below enforce against the page and the packer enforced between
* tiles), so the composition is order-independent.
*
* @param IntArray pageWidths Page widths in pixels, indexed by [AtlasPackPlacement.pageIndex].
* @param IntArray pageHeights Page heights in pixels, index-parallel to [pageWidths].
* @param List items The tiles' pixels; every placement's key must resolve here.
* @param List placements Where each tile goes.
* @param Int extrude How many pixels of each tile's edge color are bled into the gutter, at zero alpha.
* @return List The composed pages, RGBA8888, in page-index order.
*/
public fun composeAtlasPages(
pageWidths: IntArray,
pageHeights: IntArray,
items: List<AtlasPackItem>,
placements: List<AtlasPackPlacement>,
extrude: Int,
): List<RasterImage> {
require(pageWidths.size == pageHeights.size) {
"page width and height lists must be index-parallel: ${pageWidths.size} vs ${pageHeights.size}"
}
require(extrude >= 0) { "extrude must be non-negative: $extrude" }
val itemByKey = items.associateBy { item -> item.key }
require(itemByKey.size == items.size) { "atlas pack item keys must be unique" }
val pageBuffers = List(pageWidths.size) { pageIndex -> ByteArray(pageWidths[pageIndex] * pageHeights[pageIndex] * 4) }
for (placement in placements) {
val item = requireNotNull(itemByKey[placement.key]) { "placement '${placement.key}' has no item" }
require(placement.quarterTurns in 0..1) {
"placement '${placement.key}' has an unsupported rotation: ${placement.quarterTurns} quarter turns"
}
require(
placement.trimLeft >= 0 &&
placement.trimTop >= 0 &&
placement.trimLeft + placement.trimWidth <= item.width &&
placement.trimTop + placement.trimHeight <= item.height,
) {
"placement '${placement.key}' trims outside its ${item.width}x${item.height} raster"
}
val pageWidth = pageWidths.getOrNull(placement.pageIndex)
val pageHeight = pageHeights.getOrNull(placement.pageIndex)
require(pageWidth != null && pageHeight != null) {
"placement '${placement.key}' names page ${placement.pageIndex} of ${pageWidths.size}"
}
require(
placement.pageX - extrude >= 0 &&
placement.pageY - extrude >= 0 &&
placement.pageX + placement.pageWidth + extrude <= pageWidth &&
placement.pageY + placement.pageHeight + extrude <= pageHeight,
) {
"placement '${placement.key}' plus its $extrude px extrusion falls outside its ${pageWidth}x$pageHeight page"
}
val trim = LayerBounds(placement.trimLeft, placement.trimTop, placement.trimWidth, placement.trimHeight)
blitTile(
page = pageBuffers[placement.pageIndex],
pageWidth = pageWidth,
sourceRgba = item.rgba,
sourceWidth = item.width,
trim = trim,
destinationX = placement.pageX,
destinationY = placement.pageY,
quarterTurns = placement.quarterTurns,
)
extrudeTileEdges(
page = pageBuffers[placement.pageIndex],
pageWidth = pageWidth,
sourceRgba = item.rgba,
sourceWidth = item.width,
trim = trim,
tileX = placement.pageX,
tileY = placement.pageY,
quarterTurns = placement.quarterTurns,
extrude = extrude,
)
}
return pageBuffers.mapIndexed { pageIndex, buffer -> RasterImage(pageWidths[pageIndex], pageHeights[pageIndex], buffer) }
}
/**
* One tile placed on a page by an arbitrary 2x3 affine over tile pixels - the shape a hand-authored
* placement takes once a rigger has rotated or scaled it, which [AtlasPackPlacement]'s integer rect
* plus quarter turn cannot hold.
*
* @property String key The tile's key into the items list.
* @property Int pageIndex The page the tile lands on.
* @property LayerBounds trim The opaque sub-rectangle of the tile's raster that is drawn, raster-local.
* @property FloatArray tileToPage The affine (m00, m01, m02, m10, m11, m12) mapping tile pixels to
* page pixels, both frames y-down with pixel (x, y) spanning [x, x + 1) by [y, y + 1).
*/
public class AtlasTilePlacement(
public val key: String,
public val pageIndex: Int,
public val trim: LayerBounds,
public val tileToPage: FloatArray,
) {
init {
require(tileToPage.size == 6) { "placement '$key' needs a 2x3 affine, got ${tileToPage.size} components" }
}
}
/**
* Composes atlas pages from placements given as affines - [composeAtlasPages] for tiles that may sit
* rotated, scaled, off the pixel grid, or partly off the page.
*
* A placement that is an exact integer translation, or an exact counter-clockwise quarter turn on
* integer pixels, with room for its bleed band takes the packer's own blit and edge bleed, so a
* page composed here from a repack's placements is byte-identical to the page the packer composed,
* turned tiles included. Every other placement is resampled: each page pixel reads the tile
* bilinearly at its center's pre-image, against transparency beyond the trim, so an edge off the pixel
* grid lands with the partial coverage it has - the way the editor resamples its own pages. A page
* pixel the tile does not cover within [extrude] pixels of the footprint takes the nearest edge's color
* at zero alpha - the packer's bleed band, expressed so it holds under rotation. Pixels that fall off
* the page are dropped rather than refused: the placement is a rigger's authored choice, and clipping
* is what the page would show.
*
* Unlike the packer's placements, hand-authored footprints may overlap; they paint in list order
* under the content-preserving rule (a later transparent sample never erases an earlier tile, a later
* opaque one wins).
*
* @param IntArray pageWidths Page widths in pixels, indexed by [AtlasTilePlacement.pageIndex].
* @param IntArray pageHeights Page heights in pixels, index-parallel to [pageWidths].
* @param List items The tiles' pixels; every placement's key must resolve here.
* @param List placements Where each tile goes.
* @param Int extrude How many pixels of each tile's edge color are bled outward, at zero alpha.
* @return List The composed pages, RGBA8888 straight alpha, in page-index order.
*/
public fun composeAtlasPagesAffine(
pageWidths: IntArray,
pageHeights: IntArray,
items: List<AtlasPackItem>,
placements: List<AtlasTilePlacement>,
extrude: Int,
): List<RasterImage> {
require(pageWidths.size == pageHeights.size) {
"page width and height lists must be index-parallel: ${pageWidths.size} vs ${pageHeights.size}"
}
require(extrude >= 0) { "extrude must be non-negative: $extrude" }
val itemByKey = items.associateBy { item -> item.key }
require(itemByKey.size == items.size) { "atlas pack item keys must be unique" }
val pageBuffers = List(pageWidths.size) { pageIndex -> ByteArray(pageWidths[pageIndex] * pageHeights[pageIndex] * 4) }
for (placement in placements) {
val item = requireNotNull(itemByKey[placement.key]) { "placement '${placement.key}' has no item" }
val trim = placement.trim
require(
trim.left >= 0 &&
trim.top >= 0 &&
trim.left + trim.width <= item.width &&
trim.top + trim.height <= item.height,
) {
"placement '${placement.key}' trims outside its ${item.width}x${item.height} raster"
}
val pageWidth = pageWidths.getOrNull(placement.pageIndex)
val pageHeight = pageHeights.getOrNull(placement.pageIndex)
require(pageWidth != null && pageHeight != null) {
"placement '${placement.key}' names page ${placement.pageIndex} of ${pageWidths.size}"
}
if (trim.width <= 0 || trim.height <= 0) {
continue
}
paintTilePlacement(pageBuffers[placement.pageIndex], pageWidth, pageHeight, item, trim, placement.tileToPage, extrude)
}
return pageBuffers.mapIndexed { pageIndex, buffer -> RasterImage(pageWidths[pageIndex], pageHeights[pageIndex], buffer) }
}
/**
* Paints one tile onto a page through its affine: the packer's own blit and edge bleed when the
* affine is one of the packer's exact placements with room for the band, else the resampling blit.
*
* The ONE path a hand-authored placement takes, whether [composeAtlasPagesAffine] derives it from a
* model or [packAtlas] keeps it as a fixed tile beside the tiles it packed, so a page the packer
* composed and the page a derivation composes from the same placement cannot differ.
*
* @param ByteArray page The destination page, RGBA8888 row-major from the top.
* @param Int pageWidth The page width in pixels.
* @param Int pageHeight The page height in pixels.
* @param AtlasPackItem item The tile's pixels.
* @param LayerBounds trim The opaque sub-rectangle of the tile that is drawn, raster-local.
* @param FloatArray tileToPage The affine mapping tile pixels to page pixels.
* @param Int extrude How many pixels of edge color to bleed outward, at zero alpha.
*/
internal fun paintTilePlacement(
page: ByteArray,
pageWidth: Int,
pageHeight: Int,
item: AtlasPackItem,
trim: LayerBounds,
tileToPage: FloatArray,
extrude: Int,
) {
val exact = exactPlacement(tileToPage, trim)
if (exact != null &&
exact.originX - extrude >= 0 &&
exact.originY - extrude >= 0 &&
exact.originX + exact.placedWidth(trim) + extrude <= pageWidth &&
exact.originY + exact.placedHeight(trim) + extrude <= pageHeight
) {
blitTile(page, pageWidth, item.rgba, item.width, trim, exact.originX, exact.originY, exact.quarterTurns)
extrudeTileEdges(page, pageWidth, item.rgba, item.width, trim, exact.originX, exact.originY, exact.quarterTurns, extrude)
} else {
blitTileAffine(page, pageWidth, pageHeight, item.rgba, item.width, trim, tileToPage, extrude)
}
}
/**
* The page-space bounding box of a tile-local rectangle through an affine - its four corners mapped
* and their extremes taken, so a rotated rectangle's box is the box of its turned corners.
*
* @param FloatArray affine The affine (m00, m01, m02, m10, m11, m12) mapping tile pixels to page pixels.
* @param Float left The rectangle's left edge, tile-local.
* @param Float top The rectangle's top edge.
* @param Float right The rectangle's right edge, exclusive.
* @param Float bottom The rectangle's bottom edge, exclusive.
* @return FloatArray The box as (left, top, right, bottom) in continuous page pixels.
*/
internal fun affineBounds(
affine: FloatArray,
left: Float,
top: Float,
right: Float,
bottom: Float,
): FloatArray {
var minX = Float.POSITIVE_INFINITY
var minY = Float.POSITIVE_INFINITY
var maxX = Float.NEGATIVE_INFINITY
var maxY = Float.NEGATIVE_INFINITY
for (cornerIndex in 0 until 4) {
val cornerX = if (cornerIndex and 1 == 0) left else right
val cornerY = if (cornerIndex and 2 == 0) top else bottom
val pageX = affine[0] * cornerX + affine[1] * cornerY + affine[2]
val pageY = affine[3] * cornerX + affine[4] * cornerY + affine[5]
minX = minOf(minX, pageX)
minY = minOf(minY, pageY)
maxX = maxOf(maxX, pageX)
maxY = maxOf(maxY, pageY)
}
return floatArrayOf(minX, minY, maxX, maxY)
}
/**
* How far a rotation term may sit from zero and still read as one of the packer's quarter turns.
*
* A placement rotated by -90 degrees carries cos(-pi / 2) in its diagonal, which is near zero in
* float, not zero; the sine terms are exact. Anything a real hand rotation produces is orders of
* magnitude farther from a quarter turn than this.
*/
private const val EXACT_TURN_EPSILON = 1e-6f
/**
* A placement the packer's own blit serves: the page pixel the placed tile's top-left lands on and
* how the tile is turned there.
*
* @property Int originX The placed tile's left edge on the page.
* @property Int originY The placed tile's top edge on the page.
* @property Int quarterTurns 0 for upright, 1 for one counter-clockwise quarter turn.
*/
private class ExactPlacement(
val originX: Int,
val originY: Int,
val quarterTurns: Int,
) {
/**
* The placed footprint's width for [trim]: a turn swaps the trim's sides.
*
* @param LayerBounds trim The tile's drawn sub-rectangle.
* @return Int The on-page width in pixels.
*/
fun placedWidth(trim: LayerBounds): Int = if (quarterTurns == 0) trim.width else trim.height
/**
* The placed footprint's height for [trim].
*
* @param LayerBounds trim The tile's drawn sub-rectangle.
* @return Int The on-page height in pixels.
*/
fun placedHeight(trim: LayerBounds): Int = if (quarterTurns == 0) trim.height else trim.width
}
/**
* Classifies [placement] as one the packer's blit serves - an exact integer translation, or an exact
* counter-clockwise quarter turn landing on integer pixels - else null.
*
* The turned case is the affine the packer's own turn induces over the untrimmed tile frame: it sends
* trim-local (u, v) to (originX + v, originY + trimWidth - u), so the placed top-left sits at
* (m02 + trim.top, m12 - trim.left - trim.width). Recognising it here is what lets a repack that
* turned a tile derive byte-identical pages instead of resampling through the bilinear path, whose
* bleed band rounds corners differently from the packer's.
*
* @param FloatArray affine The tile-to-page affine to classify.
* @param LayerBounds trim The tile's drawn sub-rectangle, raster-local.
* @return ExactPlacement? The blit origin and turn, or null when the affine scales, rotates by
* anything but a packer turn, or lands between pixels.
*/
private fun exactPlacement(affine: FloatArray, trim: LayerBounds): ExactPlacement? {
val quarterTurns: Int
val originX: Float
val originY: Float
if (affine[0] == 1f && affine[1] == 0f && affine[3] == 0f && affine[4] == 1f) {
quarterTurns = 0
originX = affine[2] + trim.left
originY = affine[5] + trim.top
} else if (abs(affine[0]) <= EXACT_TURN_EPSILON && affine[1] == 1f && affine[3] == -1f && abs(affine[4]) <= EXACT_TURN_EPSILON) {
quarterTurns = 1
originX = affine[2] + trim.top
originY = affine[5] - trim.left - trim.width
} else {
return null
}
val pixelX = originX.roundToInt()
val pixelY = originY.roundToInt()
if (pixelX.toFloat() != originX || pixelY.toFloat() != originY) {
return null
}
return ExactPlacement(pixelX, pixelY, quarterTurns)
}
/**
* Inverts a 2x3 affine, or null when it is singular.
*
* @param FloatArray affine The affine (m00, m01, m02, m10, m11, m12).
* @return FloatArray? The inverse.
*/
private fun invertAffine2x3(affine: FloatArray): FloatArray? {
val determinant = affine[0] * affine[4] - affine[1] * affine[3]
if (determinant == 0f) {
return null
}
val m00 = affine[4] / determinant
val m01 = -affine[1] / determinant
val m10 = -affine[3] / determinant
val m11 = affine[0] / determinant
return floatArrayOf(
m00,
m01,
-(m00 * affine[2] + m01 * affine[5]),
m10,
m11,
-(m10 * affine[2] + m11 * affine[5]),
)
}
/**
* Resamples one trimmed tile onto a page through an affine, clipping to the page.
*
* Runs over the footprint's bounding box grown by the bleed band plus the one texel a bilinear tap
* reaches past the trim, and inverse-maps each page pixel center into the tile. The tile is sampled
* bilinearly there against TRANSPARENCY beyond the trim ([sampleBilinearCovered]), so an edge that
* falls between page pixels paints the partial coverage it has, and nothing paints farther out than
* the art reaches. A pixel the tile does not cover at all takes the nearest edge's color at zero alpha
* when that edge, mapped back to the page, lies within [extrude] pixels - the packer's bleed band as a
* band of constant width around the footprint whatever its orientation - and is left untouched beyond
* it. Both go through the content-preserving rule; the band as synthetic.
*
* @param ByteArray page The destination page, RGBA8888 row-major from the top.
* @param Int pageWidth The page width in pixels.
* @param Int pageHeight The page height in pixels.
* @param ByteArray sourceRgba The source raster, RGBA8888 row-major from the top.
* @param Int sourceWidth The source raster's width in pixels (its row stride).
* @param LayerBounds trim The opaque sub-rectangle of the source to draw, raster-local.
* @param FloatArray tileToPage The affine mapping tile pixels to page pixels.
* @param Int extrude How many pixels of edge color to bleed outward, at zero alpha.
*/
internal fun blitTileAffine(
page: ByteArray,
pageWidth: Int,
pageHeight: Int,
sourceRgba: ByteArray,
sourceWidth: Int,
trim: LayerBounds,
tileToPage: FloatArray,
extrude: Int,
) {
val pageToTile = invertAffine2x3(tileToPage) ?: return
val trimLeft = trim.left.toFloat()
val trimTop = trim.top.toFloat()
val trimRight = (trim.left + trim.width).toFloat()
val trimBottom = (trim.top + trim.height).toFloat()
// The footprint's page-space bounding box: the four trim corners through the affine. A bilinear tap
// reaches half a texel past the trim, so coverage can land up to one page pixel past the box even
// with no band; the scan reaches whichever is farther.
val bounds = affineBounds(tileToPage, trimLeft, trimTop, trimRight, trimBottom)
val reach = maxOf(extrude, 1)
val startColumn = floor(bounds[0] - reach).toInt().coerceAtLeast(0)
val endColumn = ceil(bounds[2] + reach).toInt().coerceAtMost(pageWidth)
val startRow = floor(bounds[1] - reach).toInt().coerceAtLeast(0)
val endRow = ceil(bounds[3] + reach).toInt().coerceAtMost(pageHeight)
if (startColumn >= endColumn || startRow >= endRow) {
return
}
val extrudeSquared = extrude.toFloat() * extrude.toFloat()
val lastColumn = trim.left + trim.width - 1
val lastRow = trim.top + trim.height - 1
val sample = IntArray(4)
for (pageRow in startRow until endRow) {
val centerY = pageRow + 0.5f
for (pageColumn in startColumn until endColumn) {
val centerX = pageColumn + 0.5f
val tileX = pageToTile[0] * centerX + pageToTile[1] * centerY + pageToTile[2]
val tileY = pageToTile[3] * centerX + pageToTile[4] * centerY + pageToTile[5]
sampleBilinearCovered(sourceRgba, sourceWidth, trim.left, trim.top, lastColumn, lastRow, tileX, tileY, sample)
val pageOffset = (pageRow * pageWidth + pageColumn) * 4
val clampedX = tileX.coerceIn(trimLeft, trimRight)
val clampedY = tileY.coerceIn(trimTop, trimBottom)
val insideTrim = clampedX == tileX && clampedY == tileY
if (sample[3] > 0 || insideTrim) {
// The tile's own pixels, a transparent one included, and the partial coverage of an edge.
writeSample(page, pageOffset, sample[0], sample[1], sample[2], sample[3], synthetic = false)
continue
}
if (extrude == 0) {
continue
}
val backX = tileToPage[0] * clampedX + tileToPage[1] * clampedY + tileToPage[2]
val backY = tileToPage[3] * clampedX + tileToPage[4] * clampedY + tileToPage[5]
val deltaX = backX - centerX
val deltaY = backY - centerY
if (deltaX * deltaX + deltaY * deltaY > extrudeSquared) {
continue
}
writeSample(page, pageOffset, sample[0], sample[1], sample[2], 0, synthetic = true)
}
}
}
/**
* Samples the tile at a continuous tile-space point, bilinearly over the four surrounding texels, with
* every texel beyond the trim transparent.
*
* Transparent beyond the trim, not clamped to it: the art ends at the trim's edge, and a pixel center
* half a texel past an opaque edge must come out half covered - which is also how the editor resamples
* a tile it places between pixels. A tap beyond the trim still lends the nearest edge texel's color, so
* a point no texel covers carries the edge's color at zero alpha, and the covered texels' colors are
* averaged by their alpha: straight-alpha texels interpolate in premultiplied space and convert back,
* because averaging straight RGB across an alpha edge drags the matte color into the visible pixels. A
* point exactly on a texel center copies that texel verbatim, so an integer-aligned placement (a quarter
* turn, an exact translation the packer's blit could not take) stays byte-exact.
*
* @param ByteArray source The source raster, RGBA8888 row-major from the top.
* @param Int sourceWidth The source raster's row stride in pixels.
* @param Int firstColumn The trim's first column.
* @param Int firstRow The trim's first row.
* @param Int lastColumn The trim's last column, inclusive.
* @param Int lastRow The trim's last row, inclusive.
* @param Float sampleX The tile-space x to sample (texel (x, y) spans [x, x + 1)).
* @param Float sampleY The tile-space y to sample.
* @param IntArray out Receives the sample as (red, green, blue, alpha), 0..255.
*/
private fun sampleBilinearCovered(
source: ByteArray,
sourceWidth: Int,
firstColumn: Int,
firstRow: Int,
lastColumn: Int,
lastRow: Int,
sampleX: Float,
sampleY: Float,
out: IntArray,
) {
val x = sampleX - 0.5f
val y = sampleY - 0.5f
val floorX = floor(x)
val floorY = floor(y)
val fractionX = x - floorX
val fractionY = y - floorY
val baseColumn = floorX.toInt()
val baseRow = floorY.toInt()
var red = 0f
var green = 0f
var blue = 0f
var alpha = 0f
var straightRed = 0f
var straightGreen = 0f
var straightBlue = 0f
for (tapIndex in 0 until 4) {
val column = if (tapIndex and 1 == 0) baseColumn else baseColumn + 1
val row = if (tapIndex and 2 == 0) baseRow else baseRow + 1
val weight =
when (tapIndex) {
0 -> (1f - fractionX) * (1f - fractionY)
1 -> fractionX * (1f - fractionY)
2 -> (1f - fractionX) * fractionY
else -> fractionX * fractionY
}
if (weight == 0f) {
continue
}
val inside = column in firstColumn..lastColumn && row in firstRow..lastRow
val offset = (row.coerceIn(firstRow, lastRow) * sourceWidth + column.coerceIn(firstColumn, lastColumn)) * 4
val tapRed = (source[offset].toInt() and 0xFF).toFloat()
val tapGreen = (source[offset + 1].toInt() and 0xFF).toFloat()
val tapBlue = (source[offset + 2].toInt() and 0xFF).toFloat()
val tapAlpha = if (inside) (source[offset + 3].toInt() and 0xFF).toFloat() else 0f
if (weight == 1f) {
// Exactly on one texel's center: that texel, verbatim (at zero alpha when it lies beyond the trim).
out[0] = tapRed.toInt()
out[1] = tapGreen.toInt()
out[2] = tapBlue.toInt()
out[3] = tapAlpha.toInt()
return
}
red += weight * tapRed * tapAlpha
green += weight * tapGreen * tapAlpha
blue += weight * tapBlue * tapAlpha
alpha += weight * tapAlpha
straightRed += weight * tapRed
straightGreen += weight * tapGreen
straightBlue += weight * tapBlue
}
if (alpha > 0f) {
out[0] = (red / alpha).roundToInt().coerceIn(0, 255)
out[1] = (green / alpha).roundToInt().coerceIn(0, 255)
out[2] = (blue / alpha).roundToInt().coerceIn(0, 255)
} else {
// Nothing covered: keep the color the texels carry rather than inventing black.
out[0] = straightRed.roundToInt().coerceIn(0, 255)
out[1] = straightGreen.roundToInt().coerceIn(0, 255)
out[2] = straightBlue.roundToInt().coerceIn(0, 255)
}
out[3] = alpha.roundToInt().coerceIn(0, 255)
}
@@ -0,0 +1,323 @@
package org.umamo.format.atlas
/*
* The rectangle bin packer behind the atlas packer: pure integer geometry with no art types and no
* pixels, so it is testable on its own and reusable by any other page-composition caller.
*
* MaxRects with best-short-side-fit (Jukka Jylanki, "A Thousand Ways to Pack the Bin"): each page
* keeps a list of maximal free rectangles; a request goes into the free rectangle that leaves the
* smallest short-side remainder, and every free rectangle the placement overlaps is then split and
* the contained ones pruned. Pages are tried in order and a new one opens only when none fits.
*/
/** One rectangle to place: the caller's index plus the page footprint it needs, gutter included. */
internal class RectPackRequest(
val itemIndex: Int,
val width: Int,
val height: Int,
)
/**
* One rectangle decided before the pack runs: the page it holds and the footprint it keeps there,
* gutter included. A seed is occupied before any request is placed, so every free placement packs
* around it; it is never placed, reported, or turned.
*/
internal class RectPackSeed(
val pageIndex: Int,
val x: Int,
val y: Int,
val width: Int,
val height: Int,
)
/** Where one request landed: its page, the footprint's top-left, and whether it was quarter-turned. */
internal class RectPackSlot(
val itemIndex: Int,
val pageIndex: Int,
val x: Int,
val y: Int,
val rotated: Boolean,
)
/**
* The packing outcome.
*
* [usedWidths] / [usedHeights] are the extent actually occupied on each page - the maximum right and
* bottom edge of any footprint - which is what a shrink-to-fit caller crops to. Because a footprint
* already carries its gutter on every side, that extent includes the trailing gutter margin.
*/
internal class RectPackLayout(
val slots: List<RectPackSlot>,
val oversizedItemIndices: List<Int>,
val usedWidths: List<Int>,
val usedHeights: List<Int>,
)
/**
* Packs footprints onto as many equally-sized pages as they need.
*
* Requests are packed in descending max-side order, which is what makes MaxRects behave: the large
* awkward pieces claim their space while the free list is still coarse, and the small ones fill the
* remainders. The caller is responsible for supplying a deterministic request order - this function
* preserves it exactly and adds no ordering of its own.
*
* Seeds go first: a seeded page exists whether or not a request lands on it (a seed on page 2 opens
* pages 0 and 1 too, so page indices keep their meaning), and its rectangle is taken before the first
* request is placed. The caller keeps every seed inside the page - a seed is a footprint the caller
* already decided to keep, so there is nothing sensible to do with one that does not fit.
*
* @param List requests The footprints to place, already in packing order.
* @param Int pageSize The square page side every page is packed against, in pixels.
* @param Boolean allowRotation Whether a request may be quarter-turned to fit.
* @param List seeds Footprints already decided, occupied before any request is placed.
* @return RectPackLayout The placements, the requests too large for any page, and the used extents.
*/
internal fun packRects(
requests: List<RectPackRequest>,
pageSize: Int,
allowRotation: Boolean,
seeds: List<RectPackSeed> = emptyList(),
): RectPackLayout {
require(pageSize > 0) { "pageSize must be positive: $pageSize" }
val slots = ArrayList<RectPackSlot>(requests.size)
val oversizedItemIndices = ArrayList<Int>()
val pages = ArrayList<MaxRectsPage>()
for (seed in seeds) {
require(seed.pageIndex >= 0) { "seed page index must not be negative: ${seed.pageIndex}" }
while (pages.size <= seed.pageIndex) {
pages.add(MaxRectsPage(pageSize))
}
pages[seed.pageIndex].seed(seed.x, seed.y, seed.width, seed.height)
}
for (request in requests) {
// A square page cap means a quarter turn cannot rescue an oversized request: both sides
// have to fit either way.
if (request.width > pageSize || request.height > pageSize) {
oversizedItemIndices.add(request.itemIndex)
continue
}
var placed = false
for ((pageIndex, page) in pages.withIndex()) {
val placement = page.place(request.width, request.height, allowRotation)
if (placement != null) {
slots.add(RectPackSlot(request.itemIndex, pageIndex, placement.x, placement.y, placement.rotated))
placed = true
break
}
}
if (!placed) {
val freshPage = MaxRectsPage(pageSize)
val placement =
checkNotNull(freshPage.place(request.width, request.height, allowRotation)) {
"request ${request.width}x${request.height} fits the page cap $pageSize but not an empty page"
}
pages.add(freshPage)
slots.add(RectPackSlot(request.itemIndex, pages.size - 1, placement.x, placement.y, placement.rotated))
}
}
return RectPackLayout(
slots = slots,
oversizedItemIndices = oversizedItemIndices,
usedWidths = pages.map { page -> page.usedWidth },
usedHeights = pages.map { page -> page.usedHeight },
)
}
/** A chosen position for one request, with the orientation it was accepted at. */
private class MaxRectsPlacement(val x: Int, val y: Int, val rotated: Boolean)
/** One free rectangle in the maximal-rectangles free list. */
private class FreeRect(val x: Int, val y: Int, val width: Int, val height: Int)
/** One page being packed: a square of [pageSize] plus its maximal free rectangles. */
private class MaxRectsPage(private val pageSize: Int) {
private var freeRects = mutableListOf(FreeRect(0, 0, pageSize, pageSize))
/** The furthest right edge, in pixels, that any placement on this page has reached. */
var usedWidth: Int = 0
private set
/** The furthest down edge, in pixels, that any placement on this page has reached. */
var usedHeight: Int = 0
private set
/**
* Places one footprint if it fits, choosing the free rectangle with the smallest short-side
* remainder and breaking ties on the long side.
*
* @param Int width The footprint width.
* @param Int height The footprint height.
* @param Boolean allowRotation Whether the quarter-turned orientation may be considered.
* @return MaxRectsPlacement The accepted position, or null when nothing fits.
*/
fun place(width: Int, height: Int, allowRotation: Boolean): MaxRectsPlacement? {
var bestShortSide = Int.MAX_VALUE
var bestLongSide = Int.MAX_VALUE
var bestX = -1
var bestY = -1
var bestRotated = false
for (freeRect in freeRects) {
val orientationCount = if (allowRotation) 2 else 1
for (orientationIndex in 0 until orientationCount) {
val rotated = orientationIndex == 1
val candidateWidth = if (rotated) height else width
val candidateHeight = if (rotated) width else height
if (candidateWidth > freeRect.width || candidateHeight > freeRect.height) {
continue
}
val leftoverHorizontal = freeRect.width - candidateWidth
val leftoverVertical = freeRect.height - candidateHeight
val shortSide = minOf(leftoverHorizontal, leftoverVertical)
val longSide = maxOf(leftoverHorizontal, leftoverVertical)
if (shortSide < bestShortSide || (shortSide == bestShortSide && longSide < bestLongSide)) {
bestShortSide = shortSide
bestLongSide = longSide
bestX = freeRect.x
bestY = freeRect.y
bestRotated = rotated
}
}
}
if (bestX < 0) {
return null
}
val placedWidth = if (bestRotated) height else width
val placedHeight = if (bestRotated) width else height
occupy(bestX, bestY, placedWidth, placedHeight)
usedWidth = maxOf(usedWidth, bestX + placedWidth)
usedHeight = maxOf(usedHeight, bestY + placedHeight)
return MaxRectsPlacement(bestX, bestY, bestRotated)
}
/**
* Takes a footprint decided before the pack: the free list loses it exactly as it loses a
* placement, and the used extent grows to cover it, so a page cropped to what it uses still
* holds the seed.
*
* @param Int seedX The footprint's left edge.
* @param Int seedY The footprint's top edge.
* @param Int seedWidth The footprint's width.
* @param Int seedHeight The footprint's height.
*/
fun seed(seedX: Int, seedY: Int, seedWidth: Int, seedHeight: Int) {
occupy(seedX, seedY, seedWidth, seedHeight)
usedWidth = maxOf(usedWidth, seedX + seedWidth)
usedHeight = maxOf(usedHeight, seedY + seedHeight)
}
/**
* Splits every free rectangle the placement overlaps, then drops the ones now contained.
*
* @param Int placedX The footprint's left edge.
* @param Int placedY The footprint's top edge.
* @param Int placedWidth The footprint's width.
* @param Int placedHeight The footprint's height.
*/
private fun occupy(placedX: Int, placedY: Int, placedWidth: Int, placedHeight: Int) {
val next = ArrayList<FreeRect>(freeRects.size + 4)
for (freeRect in freeRects) {
if (!splitFreeRect(freeRect, placedX, placedY, placedWidth, placedHeight, next)) {
next.add(freeRect)
}
}
freeRects = pruneContained(next)
}
/**
* Splits one free rectangle around the placed footprint, appending the surviving strips.
*
* @param FreeRect freeRect The free rectangle to split.
* @param Int placedX The footprint's left edge.
* @param Int placedY The footprint's top edge.
* @param Int placedWidth The footprint's width.
* @param Int placedHeight The footprint's height.
* @param MutableList out Receives the strips left over after the split.
* @return Boolean True when the footprint overlapped and the rectangle was consumed.
*/
private fun splitFreeRect(
freeRect: FreeRect,
placedX: Int,
placedY: Int,
placedWidth: Int,
placedHeight: Int,
out: MutableList<FreeRect>,
): Boolean {
val placedRight = placedX + placedWidth
val placedBottom = placedY + placedHeight
val freeRight = freeRect.x + freeRect.width
val freeBottom = freeRect.y + freeRect.height
if (placedX >= freeRight || placedRight <= freeRect.x || placedY >= freeBottom || placedBottom <= freeRect.y) {
return false
}
if (placedX < freeRight && placedRight > freeRect.x) {
if (placedY > freeRect.y && placedY < freeBottom) {
out.add(FreeRect(freeRect.x, freeRect.y, freeRect.width, placedY - freeRect.y))
}
if (placedBottom < freeBottom) {
out.add(FreeRect(freeRect.x, placedBottom, freeRect.width, freeBottom - placedBottom))
}
}
if (placedY < freeBottom && placedBottom > freeRect.y) {
if (placedX > freeRect.x && placedX < freeRight) {
out.add(FreeRect(freeRect.x, freeRect.y, placedX - freeRect.x, freeRect.height))
}
if (placedRight < freeRight) {
out.add(FreeRect(placedRight, freeRect.y, freeRight - placedRight, freeRect.height))
}
}
return true
}
/**
* Drops every free rectangle wholly contained in another, keeping the list maximal.
*
* The pairwise sweep is the canonical MaxRects prune. Duplicates contain each other, and the
* first check below fires for that case, so the EARLIER index is the one dropped; the survivors
* keep their relative order either way, and page layout is only deterministic if this is.
*
* @param MutableList candidates The free list after splitting, possibly with contained entries.
* @return MutableList The maximal free list.
*/
private fun pruneContained(candidates: MutableList<FreeRect>): MutableList<FreeRect> {
var candidateIndex = 0
while (candidateIndex < candidates.size) {
var otherIndex = candidateIndex + 1
var removedCandidate = false
while (otherIndex < candidates.size) {
if (contains(candidates[otherIndex], candidates[candidateIndex])) {
candidates.removeAt(candidateIndex)
removedCandidate = true
break
}
if (contains(candidates[candidateIndex], candidates[otherIndex])) {
candidates.removeAt(otherIndex)
continue
}
otherIndex++
}
if (!removedCandidate) {
candidateIndex++
}
}
return candidates
}
/**
* Whether [outer] wholly covers [inner].
*
* @param FreeRect outer The candidate containing rectangle.
* @param FreeRect inner The candidate contained rectangle.
* @return Boolean True when every corner of [inner] lies within or on the border of [outer].
*/
private fun contains(outer: FreeRect, inner: FreeRect): Boolean =
inner.x >= outer.x &&
inner.y >= outer.y &&
inner.x + inner.width <= outer.x + outer.width &&
inner.y + inner.height <= outer.y + outer.height
}
@@ -0,0 +1,58 @@
package org.umamo.format.binary
/*
* Text encodings the binary readers need, in common code.
*
* `kotlin.text.Charsets` is JVM-only despite being a default import, so `String(bytes, US_ASCII)`
* and `toByteArray(UTF_16BE)` cannot appear in commonMain. These are the two conversions the
* format readers actually use, implemented directly. Kotlin's stdlib offers no common Charset
* API, and `decodeToString()` is UTF-8 only — which is NOT a drop-in for either of these.
*/
/** Byte values above this are not representable in ASCII. */
private const val ASCII_MAX = 0x7F
/** What a malformed byte decodes to, matching the JVM's US_ASCII decoder. */
private const val REPLACEMENT_CHARACTER = '�'
/**
* Decodes [length] bytes of [bytes] at [offset] as US-ASCII.
*
* Matches the JVM's `String(bytes, offset, length, Charsets.US_ASCII)` exactly, including mapping any
* byte outside 0x00..0x7F to U+FFFD. That fidelity matters: the naive alternative (`Byte.toChar()`)
* would silently decode high bytes as Latin-1, so a corrupt signature could compare equal to
* something it is not. Note `decodeToString()` is not a substitute — it decodes UTF-8.
*
* @param ByteArray bytes The buffer to read from.
* @param Int offset Offset of the first byte.
* @param Int length Number of bytes to decode.
* @return String The decoded text.
*/
internal fun decodeAscii(bytes: ByteArray, offset: Int, length: Int): String {
val characters = CharArray(length)
for (characterIndex in 0 until length) {
val byteValue = bytes[offset + characterIndex].toInt() and 0xFF
characters[characterIndex] = if (byteValue <= ASCII_MAX) byteValue.toChar() else REPLACEMENT_CHARACTER
}
return characters.concatToString()
}
/**
* Encodes [text] as UTF-16 big-endian.
*
* Matches the JVM's `toByteArray(Charsets.UTF_16BE)`: a Kotlin `Char` is already a UTF-16 code unit,
* so writing each one big-endian is UTF-16BE by construction (surrogate pairs included, since they are
* simply two code units). No byte-order mark is emitted, which is what UTF_16BE means.
*
* @param String text The text to encode.
* @return ByteArray The UTF-16BE bytes, two per code unit.
*/
internal fun encodeUtf16Be(text: String): ByteArray {
val encoded = ByteArray(text.length * 2)
for (characterIndex in text.indices) {
val codeUnit = text[characterIndex].code
encoded[characterIndex * 2] = ((codeUnit ushr 8) and 0xFF).toByte()
encoded[characterIndex * 2 + 1] = (codeUnit and 0xFF).toByte()
}
return encoded
}
@@ -0,0 +1,130 @@
package org.umamo.format.binary
/**
* A little-or-big-endian random-access reader over a [ByteArray], shared by the codecs that parse
* structured binary headers (TIFF's II/MM directories, WebP's little-endian RIFF chunks, PSD's
* big-endian records).
*
* Also the common-code replacement for `java.nio.ByteBuffer`, which is why it carries both a cursor
* and absolute reads: it defaults to big-endian and its [position] behaves like ByteBuffer's, so a
* big-endian ByteBuffer parser ports across without restructuring. Offsets are Int (files under
* 2 GiB); 32-bit fields are read as Long to stay unsigned-safe, with [u32AsInt] for the common
* in-range case. [position] advances on the sequential read* methods; the at-offset methods do not
* move it.
*/
internal class ByteReader(
val bytes: ByteArray,
var position: Int = 0,
var littleEndian: Boolean = false,
) {
/**
* Reads an unsigned byte at [at] without moving [position].
*
* @param Int at Absolute offset.
* @return Int The value in 0..255.
*/
fun u8(at: Int): Int = bytes[at].toInt() and 0xFF
/**
* Reads an unsigned 16-bit value at [at] in the current byte order, without moving [position].
*
* @param Int at Absolute offset of the first byte.
* @return Int The value in 0..65535.
*/
fun u16(at: Int): Int =
if (littleEndian) {
u8(at) or (u8(at + 1) shl 8)
} else {
(u8(at) shl 8) or u8(at + 1)
}
/**
* Reads an unsigned 32-bit value at [at] in the current byte order (as a Long), without moving
* [position].
*
* @param Int at Absolute offset of the first byte.
* @return Long The value in 0..4294967295.
*/
fun u32(at: Int): Long =
if (littleEndian) {
(u8(at).toLong()) or (u8(at + 1).toLong() shl 8) or (u8(at + 2).toLong() shl 16) or (u8(at + 3).toLong() shl 24)
} else {
(u8(at).toLong() shl 24) or (u8(at + 1).toLong() shl 16) or (u8(at + 2).toLong() shl 8) or u8(at + 3).toLong()
}
/**
* Reads an unsigned 32-bit value at [at] as an Int (for offsets/counts within the 2 GiB range).
*
* @param Int at Absolute offset of the first byte.
* @return Int The value truncated to Int.
*/
fun u32AsInt(at: Int): Int = u32(at).toInt()
/**
* Reads an unsigned byte at [position], then advances by one.
*
* @return Int The value in 0..255.
*/
fun readU8(): Int = u8(position).also { position += 1 }
/**
* Reads an unsigned 16-bit value at [position], then advances by two.
*
* @return Int The value in 0..65535.
*/
fun readU16(): Int = u16(position).also { position += 2 }
/**
* Reads an unsigned 32-bit value at [position] (as a Long), then advances by four.
*
* @return Long The value in 0..4294967295.
*/
fun readU32(): Long = u32(position).also { position += 4 }
/**
* Reads an unsigned 32-bit value at [position] as an Int, then advances by four.
*
* @return Int The value truncated to Int.
*/
fun readU32AsInt(): Int = u32AsInt(position).also { position += 4 }
/**
* Reads a signed 16-bit value at [position], then advances by two.
*
* @return Int The sign-extended value in -32768..32767.
*/
fun readI16(): Int = readU16().toShort().toInt()
/**
* Reads [count] bytes at [position], then advances by that many.
*
* @param Int count Number of bytes to copy.
* @return ByteArray The bytes read.
*/
fun readBytes(count: Int): ByteArray = bytes.copyOfRange(position, position + count).also { position += count }
/**
* Reads [count] bytes at [at] and decodes them as US-ASCII, without moving [position].
*
* For the fixed 4-character tags binary formats use as signatures and keys (PSD's `8BIM`/`lyid`,
* RIFF's `WEBP`). Strictly ASCII, via [decodeAscii]: any byte above 0x7F becomes U+FFFD rather
* than a Latin-1 character, so a corrupt tag cannot compare equal to something it is not. NOT for
* arbitrary text - a format's human-readable strings (a PSD layer name, say) carry a real encoding
* and must be decoded with it; see [readBytes] plus `decodeToString()` for UTF-8.
*
* @param Int at Absolute offset of the first byte.
* @param Int count Number of bytes to decode.
* @return String The decoded text.
*/
fun asciiAt(at: Int, count: Int): String = decodeAscii(bytes, at, count)
/**
* Reads [count] bytes at [position] and decodes them as US-ASCII, then advances by that many.
*
* Carries [asciiAt]'s constraints: fixed tags only, never arbitrary text.
*
* @param Int count Number of bytes to decode.
* @return String The decoded text.
*/
fun readAscii(count: Int): String = asciiAt(position, count).also { position += count }
}
@@ -0,0 +1,19 @@
package org.umamo.format.binary
import okio.ByteString.Companion.toByteString
/*
* The content hash the document records for what it read - a file's bytes, a layer's pixels - and
* that the re-import compares against: the watcher to skip a save that changed nothing, the matcher to
* recognize a renamed layer whose pixels did not change. One algorithm, named here and nowhere else:
* SHA-256 as lowercase hex, which is what the native format persists (docs/format/UMA.md §6.4).
* :storage's contentHashOfFile is the streaming form of the same digest for a file on disk.
*/
/**
* The content hash of [bytes].
*
* @param ByteArray bytes The bytes.
* @return String The digest as lowercase hex.
*/
fun contentHashOf(bytes: ByteArray): String = bytes.toByteString().sha256().hex()
@@ -0,0 +1,102 @@
package org.umamo.format.binary
/**
* The CRC-32 lookup table for the reflected IEEE 802.3 polynomial (0xEDB88320), built once.
*
* Each entry is the CRC of a single byte value, so the update loop is one table lookup per byte.
*/
private val CRC32_TABLE: IntArray =
IntArray(256) { tableIndex ->
var remainder = tableIndex
repeat(8) {
remainder =
if ((remainder and 1) != 0) {
(remainder ushr 1) xor 0xEDB88320.toInt()
} else {
remainder ushr 1
}
}
remainder
}
/**
* Eight chained CRC-32 tables for slicing-by-8, 256 entries each, laid end to end: table 0 is
* [CRC32_TABLE], and entry i of table k is the CRC of byte i followed by k zero bytes. Looking up
* each of eight input bytes in its own table and XOR-ing the results advances the checksum by eight
* bytes at once, with the eight lookups independent of each other instead of each waiting on the last.
*/
private val CRC32_SLICE_TABLES: IntArray =
IntArray(8 * 256).also { tables ->
CRC32_TABLE.copyInto(tables)
for (tableIndex in 1 until 8) {
for (byteValue in 0 until 256) {
val shorter = tables[(tableIndex - 1) * 256 + byteValue]
tables[tableIndex * 256 + byteValue] = (shorter ushr 8) xor CRC32_TABLE[shorter and 0xFF]
}
}
}
/**
* CRC-32 (IEEE 802.3), the checksum PNG stamps on every chunk (PNG spec §5.3) and ZIP on every entry
* (APPNOTE.TXT 4.3.9) — hence a shared utility here rather than something a single codec owns.
*
* A pure-Kotlin equivalent of `java.util.zip.CRC32`, mirroring its shape (accumulate with [update],
* read with [value]) so the codecs that use it stay in commonMain and compile for every target.
*/
internal class Crc32 {
// The running remainder, pre-conditioned to all-ones per the standard.
private var remainder = -1
/**
* Folds every byte of [bytes] into the running checksum.
*
* @param ByteArray bytes The bytes to accumulate.
*/
fun update(bytes: ByteArray) {
update(bytes, 0, bytes.size)
}
/**
* Folds [length] bytes of [bytes] starting at [offset] into the running checksum, so a caller can
* checksum a slice of a larger buffer without copying it out.
*
* @param ByteArray bytes The buffer holding the bytes.
* @param Int offset Offset of the first byte to accumulate.
* @param Int length Number of bytes to accumulate.
*/
fun update(bytes: ByteArray, offset: Int, length: Int) {
val tables = CRC32_SLICE_TABLES
val end = offset + length
var running = remainder
var byteIndex = offset
while (end - byteIndex >= 8) {
// The reflected CRC consumes bytes least-significant first, so the first four fold into the
// running remainder as a little-endian word; the oldest byte takes the longest table.
val firstWord =
(bytes[byteIndex].toInt() and 0xFF) or
((bytes[byteIndex + 1].toInt() and 0xFF) shl 8) or
((bytes[byteIndex + 2].toInt() and 0xFF) shl 16) or
((bytes[byteIndex + 3].toInt() and 0xFF) shl 24)
val first = running xor firstWord
running =
tables[7 * 256 + (first and 0xFF)] xor
tables[6 * 256 + ((first ushr 8) and 0xFF)] xor
tables[5 * 256 + ((first ushr 16) and 0xFF)] xor
tables[4 * 256 + (first ushr 24)] xor
tables[3 * 256 + (bytes[byteIndex + 4].toInt() and 0xFF)] xor
tables[2 * 256 + (bytes[byteIndex + 5].toInt() and 0xFF)] xor
tables[256 + (bytes[byteIndex + 6].toInt() and 0xFF)] xor
tables[bytes[byteIndex + 7].toInt() and 0xFF]
byteIndex += 8
}
while (byteIndex < end) {
running = CRC32_TABLE[(running xor bytes[byteIndex].toInt()) and 0xFF] xor (running ushr 8)
byteIndex++
}
remainder = running
}
/** The checksum of everything accumulated so far, as an unsigned 32-bit value. */
val value: Long
get() = remainder.inv().toLong() and 0xFFFFFFFFL
}
@@ -0,0 +1,186 @@
package org.umamo.format.binary
import okio.Buffer
import okio.BufferedSource
import okio.Deflater
import okio.DeflaterSink
import okio.IOException
import okio.Inflater
import okio.InflaterSource
import okio.Source
import okio.buffer
/*
* DEFLATE for the raster codecs and the CMO3 CAFF container.
*
* Two framings, because the callers need both:
* - zlib (RFC 1950: 2-byte header + deflate + Adler-32) — PNG IDAT, TIFF Deflate, PSD ZIP
* channels, CLIP tiles.
* - raw deflate (no wrapper; zlib's windowBits = -15) — the payload of a ZIP entry, which is what
* the CAFF codec frames for CMO3's compressed blobs.
*/
/** Asks zlib for its default (level 6), matching java.util.zip's DEFAULT_COMPRESSION. */
private const val DEFAULT_COMPRESSION_LEVEL = -1
/**
* Inflates the zlib stream at [sourceOffset] into its decompressed bytes.
*
* Best-effort by design: a truncated or corrupt stream yields the bytes recovered so far rather than
* throwing, matching the other readers and letting a partly damaged image still decode.
*
* @param ByteArray source The buffer holding the zlib stream.
* @param Int sourceOffset Offset of the stream's first byte.
* @param Int sourceLength Compressed byte count.
* @param Int maximumSize An upper bound on the output, so a malformed stream cannot inflate without
* limit; pass the decompressed size the container states.
* @return ByteArray The inflated bytes.
*/
internal fun inflateZlib(source: ByteArray, sourceOffset: Int, sourceLength: Int, maximumSize: Int): ByteArray =
inflate(source, sourceOffset, sourceLength, maximumSize, rawDeflate = false)
/**
* Inflates a raw (unwrapped) deflate stream — the payload of a ZIP entry.
*
* @param ByteArray source The buffer holding the deflate stream.
* @param Int sourceOffset Offset of the stream's first byte.
* @param Int sourceLength Compressed byte count.
* @param Int maximumSize An upper bound on the output.
* @return ByteArray The inflated bytes.
*/
internal fun inflateRawDeflate(source: ByteArray, sourceOffset: Int, sourceLength: Int, maximumSize: Int): ByteArray =
inflate(source, sourceOffset, sourceLength, maximumSize, rawDeflate = true)
/**
* Compresses [source] to a zlib stream at the default compression level.
*
* @param ByteArray source The raw bytes to compress.
* @return ByteArray The zlib-wrapped deflate stream.
*/
internal fun deflateZlib(source: ByteArray): ByteArray = deflate(source, DEFAULT_COMPRESSION_LEVEL, rawDeflate = false)
/**
* Compresses [source] to a raw (unwrapped) deflate stream, for embedding as a ZIP entry's payload.
*
* @param ByteArray source The raw bytes to compress.
* @param Int level The DEFLATE level (0..9).
* @return ByteArray The raw deflate stream.
*/
internal fun deflateRawDeflate(source: ByteArray, level: Int): ByteArray = deflate(source, level, rawDeflate = true)
/**
* The shared inflate path.
*
* @param ByteArray source The buffer holding the stream.
* @param Int sourceOffset Offset of the stream's first byte.
* @param Int sourceLength Compressed byte count.
* @param Int maximumSize Upper bound on the output.
* @param Boolean rawDeflate True for an unwrapped stream (windowBits -15), false for zlib framing.
* @return ByteArray The inflated bytes, up to [maximumSize].
*/
private fun inflate(source: ByteArray, sourceOffset: Int, sourceLength: Int, maximumSize: Int, rawDeflate: Boolean): ByteArray {
if (sourceLength <= 0 || sourceOffset >= source.size || maximumSize <= 0) {
return ByteArray(0)
}
val available = minOf(sourceLength, source.size - sourceOffset)
val compressed = Buffer().write(source, sourceOffset, available)
// A raw stream has no trailer, and zlib wants a byte of lookahead past the final block to notice
// it is finished; without it the inflater asks for more input at the very end and okio raises EOF.
// java.util.zip documents the same "extra dummy byte" requirement for its nowrap mode.
if (rawDeflate) {
compressed.writeByte(0)
}
val inflated = Buffer()
val inflaterSource = InflaterSource(compressed, Inflater(rawDeflate))
try {
while (inflated.size < maximumSize) {
if (inflaterSource.read(inflated, maximumSize - inflated.size) == -1L) {
break
}
}
} catch (_: IOException) {
// Best-effort: return what inflated so far rather than failing the whole decode.
} finally {
// Releases the inflater. On a truncated stream close() can itself raise, which must not mask
// the bytes already recovered.
try {
inflaterSource.close()
} catch (_: IOException) {
// Already best-effort.
}
}
return inflated.readByteArray()
}
/**
* A zlib stream inflated on demand, for a caller that consumes the output a piece at a time (PNG's
* scanlines) rather than holding all of it at once.
*
* Best-effort like [inflateZlib]: a truncated or corrupt stream ends early instead of throwing, and
* every read after that point delivers nothing. The caller bounds the output by how much it asks
* for, so a stream that would inflate past what its container describes is never expanded further.
*
* @param Source compressed The zlib stream.
*/
internal class ZlibStreamReader(compressed: Source) {
private val inflated: BufferedSource = InflaterSource(compressed, Inflater(false)).buffer()
// Set once the stream has ended or broken; no read is attempted after that.
private var ended = false
/**
* Fills [destination] from [offset] with the next [count] inflated bytes, or with as many as the
* stream still holds.
*
* @param ByteArray destination The buffer to fill.
* @param Int offset Offset of the first byte to write.
* @param Int count Number of bytes wanted.
* @return Int The number of bytes written: [count] unless the stream ended or broke first.
*/
fun readFully(destination: ByteArray, offset: Int, count: Int): Int {
var filled = 0
while (filled < count && !ended) {
val read =
try {
inflated.read(destination, offset + filled, count - filled)
} catch (_: IOException) {
-1
}
if (read == -1) {
ended = true
} else {
filled += read
}
}
return filled
}
/**
* Releases the inflater. On a truncated stream close() can itself raise, which must not mask the
* bytes already delivered.
*/
fun close() {
try {
inflated.close()
} catch (_: IOException) {
// Already best-effort.
}
}
}
/**
* The shared deflate path.
*
* @param ByteArray source The raw bytes to compress.
* @param Int level The DEFLATE level.
* @param Boolean rawDeflate True to omit the zlib wrapper.
* @return ByteArray The compressed stream.
*/
private fun deflate(source: ByteArray, level: Int, rawDeflate: Boolean): ByteArray {
val deflated = Buffer()
val sink = DeflaterSink(deflated, Deflater(level, rawDeflate)).buffer()
sink.write(source)
// Finishes the stream and releases the deflater.
sink.close()
return deflated.readByteArray()
}
@@ -0,0 +1,579 @@
package org.umamo.format.binary
/*
* A strict reader for ordinary multi-entry ZIP archives, in commonMain so every target reads the same
* bytes the same way: the UMA container and the KRA reader both stand on it.
*
* Strict where the shared DEFLATE seam is deliberately lenient. inflateRawDeflate recovers what it can
* from a damaged stream, which suits a half-readable image; an archive entry instead has a declared size
* and CRC-32, and this reader holds every entry to both, so a truncated, corrupt, or lying archive fails
* loudly (docs/format/UMA.md §1).
*/
/**
* A malformed or unsupported ZIP archive, or an entry whose bytes do not match what the archive declares.
*
* @param String message What was wrong, naming the entry when there is one.
*/
internal class ZipFormatException(message: String) : RuntimeException(message)
/**
* One entry as the central directory declares it.
*
* @property String name The entry name, decoded as UTF-8.
* @property Int method The compression method (APPNOTE.TXT 4.4.5).
* @property Int flags The general purpose bit flags (APPNOTE.TXT 4.4.4).
* @property Long crc32 The CRC-32 of the uncompressed bytes, unsigned.
* @property Int compressedSize The payload's size on disk.
* @property Int uncompressedSize The entry's size once inflated.
* @property Int dosDateTime The MS-DOS modification stamp: date in the high 16 bits, time in the low 16.
* @property Int payloadOffset Where the payload starts in the archive's bytes.
* @property Int versionNeeded The "version needed to extract" (APPNOTE.TXT 4.4.3).
*/
internal class ZipEntry(
val name: String,
val method: Int,
val flags: Int,
val crc32: Long,
val compressedSize: Int,
val uncompressedSize: Int,
val dosDateTime: Int,
val payloadOffset: Int,
val versionNeeded: Int,
) {
/** True for a directory entry, which ZIP marks with a trailing slash (APPNOTE.TXT 4.4.17.1). */
val isDirectory: Boolean
get() = name.endsWith('/')
/** True when the entry is encrypted, which this reader cannot inflate. */
val isEncrypted: Boolean
get() = (flags and ZipRecords.FLAG_ENCRYPTED) != 0
}
/**
* A parsed ZIP archive over its bytes: the central directory read eagerly, each entry's payload only on
* request.
*
* Lazy payloads are what copy-through needs - a writer can carry an entry it never inflates
* ([rawPayload]) - and what lets a caller read two entries of a large archive without inflating the rest.
*
* @property List<ZipEntry> entries Every entry, in central-directory order.
*/
internal class ZipArchive private constructor(
/** The whole archive, which every entry's payload offset indexes into. */
val bytes: ByteArray,
val entries: List<ZipEntry>,
) {
private val entryByName: Map<String, ZipEntry> = entries.associateBy { entry -> entry.name }
/**
* The entry named [name], or null when the archive has none.
*
* @param String name The entry name.
* @return ZipEntry? The entry.
*/
fun entry(name: String): ZipEntry? = entryByName[name]
/**
* The entry's uncompressed bytes, verified against the sizes and CRC-32 the archive declares.
*
* The inflate is bounded one byte past the declared size, so an entry that would inflate further
* stops there and fails rather than allocating what it claims not to hold.
*
* @param ZipEntry entry An entry of this archive.
* @return ByteArray The uncompressed bytes.
* @throws ZipFormatException When the entry is encrypted, uses a method other than stored or DEFLATE,
* or its bytes do not match its declared size or CRC-32.
*/
fun contents(entry: ZipEntry): ByteArray = decodeZipPayload(entry, bytes, entry.payloadOffset)
/**
* The entry's payload exactly as stored - compressed, and encrypted if it is - for copying into another
* archive without inflating it.
*
* @param ZipEntry entry An entry of this archive.
* @return ByteArray The payload bytes.
*/
fun rawPayload(entry: ZipEntry): ByteArray = bytes.copyOfRange(entry.payloadOffset, entry.payloadOffset + entry.compressedSize)
companion object {
/** The largest size a ByteArray can hold on every target, and so the largest entry or archive read. */
private const val MAXIMUM_ARRAY_SIZE = Int.MAX_VALUE - 8
/**
* Parses [bytes] as a ZIP archive: finds the end record, follows Zip64 records where the classic
* fields overflow, walks the central directory, and validates every entry's local header.
*
* @param ByteArray bytes The whole archive.
* @return ZipArchive The parsed archive; payloads are read on request.
* @throws ZipFormatException When the archive is truncated, malformed, split across disks, or holds
* two entries with the same name.
*/
fun read(bytes: ByteArray): ZipArchive {
val reader = ByteReader(bytes, littleEndian = true)
val directory = locateCentralDirectory(reader)
val entries = ArrayList<ZipEntry>(directory.entryCount)
val names = HashSet<String>(directory.entryCount)
var position = directory.offset
val directoryEnd = directory.offset + directory.size
repeat(directory.entryCount) { entryIndex ->
val entry = readCentralEntry(reader, position, directoryEnd, directory.offset, entryIndex)
if (!names.add(entry.first.name)) {
throw ZipFormatException("the archive holds two entries named '${entry.first.name}'")
}
entries += entry.first
position = entry.second
}
if (position != directoryEnd) {
throw ZipFormatException("the central directory declares ${directory.size} bytes but its ${directory.entryCount} entries span ${position - directory.offset}")
}
return ZipArchive(bytes, entries)
}
/**
* Where the central directory is and how many entries it holds.
*
* @property Int offset The directory's first byte.
* @property Int size The directory's length in bytes.
* @property Int entryCount The number of entries.
*/
private class CentralDirectory(
val offset: Int,
val size: Int,
val entryCount: Int,
)
/**
* Finds the end of central directory record and, through it, the central directory.
*
* The record has a variable-length comment, so it is found by scanning the tail of the file. A
* candidate counts only when its comment ends exactly at the end of the file and the directory it
* describes is really there. A comment can hold bytes that look like an end record, and one at the
* very end even satisfies the comment rule, so the EARLIEST valid candidate wins: the genuine record
* precedes any look-alike its own comment contains. The scan runs upward and stops at the first
* candidate that describes a directory, so a look-alike after the genuine record is never examined and
* cannot fail the read.
*
* @param ByteReader reader The archive, little-endian.
* @return CentralDirectory The directory's extent and entry count.
*/
private fun locateCentralDirectory(reader: ByteReader): CentralDirectory {
val size = reader.bytes.size
if (size < ZipRecords.END_SIZE) {
throw ZipFormatException("$size bytes is too short to be a ZIP archive")
}
val lowestCandidate = maxOf(0, size - ZipRecords.END_SIZE - ZipRecords.MAXIMUM_COMMENT_LENGTH)
// A candidate that declares Zip64 records the archive lacks is remembered rather than thrown: a
// look-alike may still be followed by the genuine record, but if nothing qualifies, its reason
// names the actual damage instead of the generic one.
var zip64Failure: String? = null
for (candidate in lowestCandidate..size - ZipRecords.END_SIZE) {
if (reader.u32(candidate) == ZipRecords.END_SIGNATURE.toLong() &&
// ZIP: end record @ +0x14 comment length (APPNOTE.TXT 4.3.16).
candidate + ZipRecords.END_SIZE + reader.u16(candidate + 20) == size
) {
when (val match = centralDirectoryFromEnd(reader, candidate)) {
is EndRecordMatch.Found -> return match.directory
is EndRecordMatch.Zip64Missing -> zip64Failure = match.reason
EndRecordMatch.LookAlike -> Unit
}
}
}
throw ZipFormatException(zip64Failure ?: "no end of central directory record: the archive is truncated or not a ZIP")
}
/** What examining one end record candidate found. */
private sealed interface EndRecordMatch {
/**
* The candidate is the genuine record and describes [directory].
*
* @property CentralDirectory directory The directory it describes.
*/
class Found(val directory: CentralDirectory) : EndRecordMatch
/**
* The candidate carries Zip64 sentinels but no Zip64 locator precedes it, so it describes nothing
* this archive holds; [reason] is what to report if no other candidate qualifies.
*
* @property String reason The failure to report.
*/
class Zip64Missing(val reason: String) : EndRecordMatch
/** The candidate describes no directory this archive holds: bytes inside a comment. */
object LookAlike : EndRecordMatch
}
/**
* The central directory an end record describes, or why the candidate describes none: a look-alike
* inside a comment, or a Zip64 record whose locator is missing.
*
* @param ByteReader reader The archive, little-endian.
* @param Int endOffset The candidate end record's offset.
* @return EndRecordMatch The directory, or the kind of false candidate this is.
*/
private fun centralDirectoryFromEnd(reader: ByteReader, endOffset: Int): EndRecordMatch {
// ZIP: end of central directory record (APPNOTE.TXT 4.3.16) - @ +0x04 this disk, @ +0x06 the
// directory's disk, @ +0x08 entries on this disk, @ +0x0A total entries, @ +0x0C directory
// size, @ +0x10 directory offset.
val diskNumber = reader.u16(endOffset + 4)
val directoryDisk = reader.u16(endOffset + 6)
val entriesOnDisk = reader.u16(endOffset + 8)
val totalEntries = reader.u16(endOffset + 10)
val directorySize = reader.u32(endOffset + 12)
val directoryOffset = reader.u32(endOffset + 16)
val usesZip64 =
entriesOnDisk == ZipRecords.UINT16_SENTINEL ||
totalEntries == ZipRecords.UINT16_SENTINEL ||
directorySize == ZipRecords.UINT32_SENTINEL ||
directoryOffset == ZipRecords.UINT32_SENTINEL
val locatorOffset = endOffset - ZipRecords.ZIP64_LOCATOR_SIZE
val hasLocator = locatorOffset >= 0 && reader.u32(locatorOffset) == ZipRecords.ZIP64_LOCATOR_SIGNATURE.toLong()
if (usesZip64 && hasLocator) {
return EndRecordMatch.Found(zip64CentralDirectory(reader, locatorOffset))
}
// A sentinel offset or size points at nothing, so the classic checks below cannot pass; what the
// record says is that Zip64 records should precede it and do not. The caller decides whether
// that is the archive's fault or a look-alike's.
if (directorySize == ZipRecords.UINT32_SENTINEL || directoryOffset == ZipRecords.UINT32_SENTINEL) {
return EndRecordMatch.Zip64Missing("the end record declares Zip64 records, but no Zip64 locator precedes it")
}
// A classic count of exactly 0xFFFF with no Zip64 records is a legal classic archive, read as is.
if (diskNumber != 0 || directoryDisk != 0 || entriesOnDisk != totalEntries) {
// Only a genuine end record can be declared multi-disk; a look-alike is skipped instead.
return if (plausibleDirectory(reader, directoryOffset, directorySize, totalEntries.toLong(), endOffset)) {
throw ZipFormatException("multi-disk (split) archives are not supported")
} else {
EndRecordMatch.LookAlike
}
}
if (!plausibleDirectory(reader, directoryOffset, directorySize, totalEntries.toLong(), endOffset)) {
return EndRecordMatch.LookAlike
}
return EndRecordMatch.Found(CentralDirectory(directoryOffset.toInt(), directorySize.toInt(), totalEntries))
}
/**
* The central directory a Zip64 end record describes.
*
* @param ByteReader reader The archive, little-endian.
* @param Int locatorOffset The Zip64 end of central directory locator's offset.
* @return CentralDirectory The directory.
*/
private fun zip64CentralDirectory(reader: ByteReader, locatorOffset: Int): CentralDirectory {
// ZIP: Zip64 end of central directory locator (APPNOTE.TXT 4.3.15) - @ +0x04 the disk holding the
// Zip64 end record, @ +0x08 its offset, @ +0x10 the total disk count.
val recordDisk = reader.u32(locatorOffset + 4)
val recordOffset = u64AsOffset(reader, locatorOffset + 8, "Zip64 end record offset")
val totalDisks = reader.u32(locatorOffset + 16)
if (recordDisk != 0L || totalDisks > 1L) {
throw ZipFormatException("multi-disk (split) archives are not supported")
}
if (recordOffset > locatorOffset - ZipRecords.ZIP64_END_SIZE || reader.u32(recordOffset) != ZipRecords.ZIP64_END_SIGNATURE.toLong()) {
throw ZipFormatException("the Zip64 locator points at no Zip64 end record")
}
// ZIP: Zip64 end of central directory record (APPNOTE.TXT 4.3.14) - @ +0x10 this disk, @ +0x14 the
// directory's disk, @ +0x18 entries on this disk, @ +0x20 total entries, @ +0x28 directory size,
// @ +0x30 directory offset.
val diskNumber = reader.u32(recordOffset + 16)
val directoryDisk = reader.u32(recordOffset + 20)
val entriesOnDisk = u64AsOffset(reader, recordOffset + 24, "Zip64 entries on disk")
val totalEntries = u64AsOffset(reader, recordOffset + 32, "Zip64 total entries")
val directorySize = u64AsOffset(reader, recordOffset + 40, "Zip64 central directory size")
val directoryOffset = u64AsOffset(reader, recordOffset + 48, "Zip64 central directory offset")
if (diskNumber != 0L || directoryDisk != 0L || entriesOnDisk != totalEntries) {
throw ZipFormatException("multi-disk (split) archives are not supported")
}
if (!plausibleDirectory(reader, directoryOffset.toLong(), directorySize.toLong(), totalEntries.toLong(), recordOffset)) {
throw ZipFormatException("the Zip64 end record describes a central directory the archive does not hold")
}
return CentralDirectory(directoryOffset, directorySize, totalEntries)
}
/**
* Whether a declared central directory fits before its end record and starts where it should.
*
* @param ByteReader reader The archive, little-endian.
* @param Long offset The declared directory offset.
* @param Long size The declared directory size.
* @param Long entryCount The declared entry count.
* @param Int limit The offset the directory must end at or before (its end record).
* @return Boolean True when the declaration is consistent with the bytes.
*/
private fun plausibleDirectory(reader: ByteReader, offset: Long, size: Long, entryCount: Long, limit: Int): Boolean {
if (offset < 0 || size < 0 || offset + size > limit) {
return false
}
// An empty directory has no header to check, so it must sit exactly where its end record starts.
if (entryCount == 0L) {
return size == 0L && offset == limit.toLong()
}
return size >= ZipRecords.CENTRAL_HEADER_SIZE &&
entryCount * ZipRecords.CENTRAL_HEADER_SIZE <= size &&
reader.u32(offset.toInt()) == ZipRecords.CENTRAL_HEADER_SIGNATURE.toLong()
}
/**
* Reads one central directory file header and validates the local header it points at.
*
* @param ByteReader reader The archive, little-endian.
* @param Int position The central header's offset.
* @param Int directoryEnd The central directory's end, which the header must not cross.
* @param Int directoryOffset The central directory's start, which every payload must end before.
* @param Int entryIndex The entry's index, for error messages.
* @return Pair The entry and the offset of the next central header.
*/
private fun readCentralEntry(reader: ByteReader, position: Int, directoryEnd: Int, directoryOffset: Int, entryIndex: Int): Pair<ZipEntry, Int> {
if (position + ZipRecords.CENTRAL_HEADER_SIZE > directoryEnd || reader.u32(position) != ZipRecords.CENTRAL_HEADER_SIGNATURE.toLong()) {
throw ZipFormatException("central directory entry $entryIndex is truncated or missing its signature")
}
// ZIP: central directory file header (APPNOTE.TXT 4.3.12) - @ +0x06 version needed, @ +0x08 flags, @ +0x0A method,
// @ +0x0C time, @ +0x0E date, @ +0x10 crc-32, @ +0x14 compressed size, @ +0x18 uncompressed size,
// @ +0x1C name length, @ +0x1E extra length, @ +0x20 comment length, @ +0x22 disk number start,
// @ +0x2A local header offset, @ +0x2E the name.
val versionNeeded = reader.u16(position + 6)
val flags = reader.u16(position + 8)
val method = reader.u16(position + 10)
val time = reader.u16(position + 12)
val date = reader.u16(position + 14)
val crc32 = reader.u32(position + 16)
var compressedSize = reader.u32(position + 20)
var uncompressedSize = reader.u32(position + 24)
val nameLength = reader.u16(position + 28)
val extraLength = reader.u16(position + 30)
val commentLength = reader.u16(position + 32)
var diskStart = reader.u16(position + 34).toLong()
var localOffset = reader.u32(position + 42)
val nameStart = position + ZipRecords.CENTRAL_HEADER_SIZE
val extraStart = nameStart + nameLength
val nextPosition = extraStart + extraLength + commentLength
if (nextPosition > directoryEnd) {
throw ZipFormatException("central directory entry $entryIndex runs past the end of the directory")
}
val name = decodeName(reader.bytes, nameStart, nameLength, entryIndex)
// ZIP: Zip64 extended information extra field (APPNOTE.TXT 4.5.3) - present values follow in this
// order, each only when its classic field holds the sentinel.
var extraPosition = extraStart
val extraEnd = extraStart + extraLength
while (extraPosition + 4 <= extraEnd) {
val headerId = reader.u16(extraPosition)
val dataSize = reader.u16(extraPosition + 2)
val dataStart = extraPosition + 4
if (dataStart + dataSize > extraEnd) {
throw ZipFormatException("entry '$name' has a truncated extra field")
}
if (headerId == ZipRecords.ZIP64_EXTRA_ID) {
var fieldPosition = dataStart
val dataEnd = dataStart + dataSize
/**
* Reads the next 64-bit value of the Zip64 extra field.
*
* @param String what The field, for error messages.
* @return Long The value.
*/
fun nextValue(what: String): Long {
if (fieldPosition + 8 > dataEnd) {
throw ZipFormatException("entry '$name' has a Zip64 extra field too short for its $what")
}
return u64AsOffset(reader, fieldPosition, "entry '$name' $what").toLong().also { fieldPosition += 8 }
}
if (uncompressedSize == ZipRecords.UINT32_SENTINEL) {
uncompressedSize = nextValue("uncompressed size")
}
if (compressedSize == ZipRecords.UINT32_SENTINEL) {
compressedSize = nextValue("compressed size")
}
if (localOffset == ZipRecords.UINT32_SENTINEL) {
localOffset = nextValue("local header offset")
}
if (diskStart == ZipRecords.UINT16_SENTINEL.toLong()) {
if (fieldPosition + 4 > dataEnd) {
throw ZipFormatException("entry '$name' has a Zip64 extra field too short for its disk number")
}
diskStart = reader.u32(fieldPosition)
}
}
extraPosition = dataStart + dataSize
}
if (diskStart != 0L) {
throw ZipFormatException("entry '$name' starts on another disk: multi-disk archives are not supported")
}
if (uncompressedSize > MAXIMUM_ARRAY_SIZE - 1 || compressedSize > MAXIMUM_ARRAY_SIZE) {
throw ZipFormatException("entry '$name' is larger than a byte array can hold")
}
val payloadOffset = validateLocalHeader(reader, localOffset, name, nameStart, nameLength, method, directoryOffset)
if (payloadOffset.toLong() + compressedSize > directoryOffset) {
throw ZipFormatException("entry '$name' is truncated: its payload runs past the start of the central directory")
}
val entry =
ZipEntry(
name = name,
method = method,
flags = flags,
crc32 = crc32,
compressedSize = compressedSize.toInt(),
uncompressedSize = uncompressedSize.toInt(),
dosDateTime = (date shl 16) or time,
payloadOffset = payloadOffset,
versionNeeded = versionNeeded,
)
return entry to nextPosition
}
/**
* Validates the local file header an entry points at and returns where its payload starts.
*
* The payload offset comes from the LOCAL header's own name and extra lengths, which may differ from
* the central directory's copy (writers put different extra fields in each).
*
* @param ByteReader reader The archive, little-endian.
* @param Long localOffset The local header's declared offset.
* @param String name The entry's name, for error messages.
* @param Int nameStart Where the central header's name bytes start.
* @param Int nameLength The central header's name length.
* @param Int method The central header's compression method.
* @param Int directoryOffset The central directory's start.
* @return Int The payload's offset.
*/
private fun validateLocalHeader(
reader: ByteReader,
localOffset: Long,
name: String,
nameStart: Int,
nameLength: Int,
method: Int,
directoryOffset: Int,
): Int {
if (localOffset < 0 || localOffset + ZipRecords.LOCAL_HEADER_SIZE > directoryOffset) {
throw ZipFormatException("entry '$name' points at a local header outside the archive's entry data")
}
val headerOffset = localOffset.toInt()
if (reader.u32(headerOffset) != ZipRecords.LOCAL_HEADER_SIGNATURE.toLong()) {
throw ZipFormatException("entry '$name' points at bytes that are not a local file header")
}
// ZIP: local file header (APPNOTE.TXT 4.3.7) - @ +0x08 method, @ +0x1A name length, @ +0x1C extra
// length, @ +0x1E the name.
val localMethod = reader.u16(headerOffset + 8)
val localNameLength = reader.u16(headerOffset + 26)
val localExtraLength = reader.u16(headerOffset + 28)
val localNameStart = headerOffset + ZipRecords.LOCAL_HEADER_SIZE
if (localNameStart + localNameLength + localExtraLength > directoryOffset) {
throw ZipFormatException("entry '$name' has a local header that runs into the central directory")
}
if (localMethod != method) {
throw ZipFormatException("entry '$name' declares method $method centrally but $localMethod locally")
}
if (localNameLength != nameLength || !reader.bytes.rangeEquals(localNameStart, reader.bytes, nameStart, nameLength)) {
throw ZipFormatException("entry '$name' has a local header naming a different entry")
}
return localNameStart + localNameLength + localExtraLength
}
/**
* Decodes an entry name as UTF-8, the encoding the writer flags and the one java.util.zip assumes.
*
* @param ByteArray bytes The archive.
* @param Int start The name's first byte.
* @param Int length The name's length in bytes.
* @param Int entryIndex The entry's index, for error messages.
* @return String The name.
*/
private fun decodeName(bytes: ByteArray, start: Int, length: Int, entryIndex: Int): String =
try {
bytes.decodeToString(start, start + length, throwOnInvalidSequence = true)
} catch (_: CharacterCodingException) {
throw ZipFormatException("central directory entry $entryIndex has a name that is not valid UTF-8")
}
/**
* Reads an unsigned little-endian 64-bit field that must fit a byte-array offset.
*
* @param ByteReader reader The archive, little-endian.
* @param Int at The field's offset.
* @param String what The field, for error messages.
* @return Int The value.
*/
private fun u64AsOffset(reader: ByteReader, at: Int, what: String): Int {
val high = reader.u32(at + 4)
val low = reader.u32(at)
if (high != 0L || low > MAXIMUM_ARRAY_SIZE) {
throw ZipFormatException("$what exceeds what a byte array can address")
}
return low.toInt()
}
}
}
/**
* Whether [length] bytes of this array starting at [offset] equal those of [other] starting at [otherOffset].
*
* @param Int offset The first byte compared here.
* @param ByteArray other The array compared against.
* @param Int otherOffset The first byte compared there.
* @param Int length How many bytes to compare.
* @return Boolean True when every byte matches.
*/
internal fun ByteArray.rangeEquals(offset: Int, other: ByteArray, otherOffset: Int, length: Int): Boolean {
for (byteIndex in 0 until length) {
if (this[offset + byteIndex] != other[otherOffset + byteIndex]) {
return false
}
}
return true
}
/**
* An entry's uncompressed bytes from its payload wherever the payload is held - inside the archive it came
* from, or copied out of it - verified against the sizes and CRC-32 the entry declares.
*
* The inflate is bounded one byte past the declared size, so a payload that would inflate further stops there
* and fails rather than allocating what it claims not to hold.
*
* @param ZipEntry entry The entry as its archive declared it.
* @param ByteArray source The bytes holding the payload.
* @param Int payloadOffset Where the payload starts in [source].
* @return ByteArray The uncompressed bytes.
* @throws ZipFormatException When the entry is encrypted, uses a method other than stored or DEFLATE, its
* payload does not fit [source], or its bytes do not match its declared size or CRC-32.
*/
internal fun decodeZipPayload(entry: ZipEntry, source: ByteArray, payloadOffset: Int): ByteArray {
if (entry.isEncrypted) {
throw ZipFormatException("entry '${entry.name}' is encrypted")
}
if (payloadOffset < 0 || payloadOffset.toLong() + entry.compressedSize > source.size) {
throw ZipFormatException("entry '${entry.name}' has a payload that does not fit its bytes")
}
val uncompressed =
when (entry.method) {
ZipRecords.METHOD_STORED -> {
if (entry.compressedSize != entry.uncompressedSize) {
throw ZipFormatException(
"stored entry '${entry.name}' declares ${entry.compressedSize} bytes on disk but ${entry.uncompressedSize} uncompressed",
)
}
source.copyOfRange(payloadOffset, payloadOffset + entry.compressedSize)
}
ZipRecords.METHOD_DEFLATED -> {
// One byte of headroom is how an entry that inflates past its declared size is caught
// without inflating the rest of it.
inflateRawDeflate(source, payloadOffset, entry.compressedSize, entry.uncompressedSize + 1)
}
else -> throw ZipFormatException("entry '${entry.name}' uses unsupported compression method ${entry.method}")
}
if (uncompressed.size != entry.uncompressedSize) {
throw ZipFormatException(
"entry '${entry.name}' inflates to ${if (uncompressed.size > entry.uncompressedSize) "more than" else "only"} " +
"${minOf(uncompressed.size, entry.uncompressedSize)} bytes, but declares ${entry.uncompressedSize}",
)
}
val checksum = Crc32().also { crc -> crc.update(uncompressed) }.value
if (checksum != entry.crc32) {
throw ZipFormatException("entry '${entry.name}' fails its CRC-32 check")
}
return uncompressed
}
@@ -0,0 +1,114 @@
package org.umamo.format.binary
/*
* The ZIP record layout shared by the codecs that frame ZIP data: the CAFF container's single-entry
* blobs (CaffZip) and ordinary multi-entry archives (ZipArchive, ZipWriter). Constants only - each
* codec keeps its own policy (which flags it sets, whether it writes a data descriptor, which clock it
* stamps).
*
* Citations are to PKWARE's APPNOTE.TXT: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
*/
/**
* ZIP record signatures, sizes, and field values, as APPNOTE.TXT defines them. Every multi-byte field
* on disk is little-endian.
*/
internal object ZipRecords {
// ZIP: local file header signature (APPNOTE.TXT 4.3.7).
const val LOCAL_HEADER_SIGNATURE = 0x04034B50
// ZIP: data descriptor signature (APPNOTE.TXT 4.3.9.3; optional on disk, and what CAFF writes).
const val DATA_DESCRIPTOR_SIGNATURE = 0x08074B50
// ZIP: central directory file header signature (APPNOTE.TXT 4.3.12).
const val CENTRAL_HEADER_SIGNATURE = 0x02014B50
// ZIP: Zip64 end of central directory record signature (APPNOTE.TXT 4.3.14).
const val ZIP64_END_SIGNATURE = 0x06064B50
// ZIP: Zip64 end of central directory locator signature (APPNOTE.TXT 4.3.15).
const val ZIP64_LOCATOR_SIGNATURE = 0x07064B50
// ZIP: end of central directory record signature (APPNOTE.TXT 4.3.16).
const val END_SIGNATURE = 0x06054B50
// ZIP: fixed sizes before each record's variable-length fields (APPNOTE.TXT 4.3.7, 4.3.12, 4.3.14,
// 4.3.15, 4.3.16, 4.3.9.3).
const val LOCAL_HEADER_SIZE = 30
const val CENTRAL_HEADER_SIZE = 46
const val ZIP64_END_SIZE = 56
const val ZIP64_LOCATOR_SIZE = 20
const val END_SIZE = 22
const val DATA_DESCRIPTOR_SIZE = 16
// ZIP: the Zip64 end record's "size of zip64 end of central directory record" excludes its own
// leading 12 bytes (APPNOTE.TXT 4.3.14.1).
const val ZIP64_END_RECORD_REMAINDER = ZIP64_END_SIZE - 12
// ZIP: the end record's comment length is a 16-bit field (APPNOTE.TXT 4.3.16), which bounds how far
// before the end of the file the record can start.
const val MAXIMUM_COMMENT_LENGTH = 0xFFFF
// ZIP: compression methods (APPNOTE.TXT 4.4.5) - 0 stored, 8 DEFLATE.
const val METHOD_STORED = 0
const val METHOD_DEFLATED = 8
// ZIP: "version needed to extract" (APPNOTE.TXT 4.4.3.2) - 1.0 for a stored entry, 2.0 for DEFLATE,
// 4.5 for Zip64 records.
const val VERSION_STORED = 10
const val VERSION_DEFLATED = 20
const val VERSION_ZIP64 = 45
// ZIP: general purpose bit flags (APPNOTE.TXT 4.4.4) - bit 0 encrypted, bit 3 sizes and CRC in a
// trailing data descriptor, bit 11 the name is UTF-8.
const val FLAG_ENCRYPTED = 0x0001
const val FLAG_DATA_DESCRIPTOR = 0x0008
const val FLAG_UTF8_NAME = 0x0800
// ZIP: the Zip64 extended information extra field's header id (APPNOTE.TXT 4.5.3).
const val ZIP64_EXTRA_ID = 0x0001
// ZIP: a 16-bit count or 32-bit size/offset holding all ones means "see the Zip64 record"
// (APPNOTE.TXT 4.4.1.4).
const val UINT16_SENTINEL = 0xFFFF
const val UINT32_SENTINEL = 0xFFFFFFFFL
// MS-DOS timestamp bounds (APPNOTE.TXT 4.4.6). The date packs year-1980 into 7 bits, so the epoch is
// 1980 and the ceiling is 2107; a clock outside that range is clamped rather than allowed to wrap into
// a different year.
private const val DOS_EPOCH_YEAR = 1980
private const val DOS_MAXIMUM_YEAR = 2107
// MS-DOS 1980-01-01 00:00 - the clamp floor, and what an out-of-range clock falls back to.
private const val DOS_EPOCH_DATE = 0x0021
private const val DOS_EPOCH_TIME = 0x0000
/** MS-DOS 1980-01-01 00:00 as a packed stamp: the earliest instant a ZIP header can record. */
const val DOS_EPOCH_DATE_TIME = (DOS_EPOCH_DATE shl 16) or DOS_EPOCH_TIME
/**
* Packs a local date and time into the MS-DOS format ZIP headers use.
*
* Date: year-1980 in bits 15..9, month in 8..5, day in 4..0. Time: hour in 15..11, minute in
* 10..5, and seconds HALVED into 4..0 - which is why a DOS stamp has two-second resolution.
*
* A year outside 1980..2107 cannot be expressed in the 7 bits available, so it clamps to the epoch
* rather than wrapping into a wrong-but-plausible year.
*
* @param Int year Local year.
* @param Int month Local month, 1..12.
* @param Int day Local day of month, 1..31.
* @param Int hour Local hour, 0..23.
* @param Int minute Local minute, 0..59.
* @param Int second Local second, 0..59.
* @return Int The stamp: date in the high 16 bits, time in the low 16.
*/
fun dosDateTimeOf(year: Int, month: Int, day: Int, hour: Int, minute: Int, second: Int): Int {
if (year < DOS_EPOCH_YEAR || year > DOS_MAXIMUM_YEAR) {
return DOS_EPOCH_DATE_TIME
}
val date = ((year - DOS_EPOCH_YEAR) shl 9) or (month shl 5) or day
val time = (hour shl 11) or (minute shl 5) or (second / 2)
return (date shl 16) or time
}
}
@@ -0,0 +1,315 @@
package org.umamo.format.binary
import okio.Buffer
/**
* Builds an ordinary multi-entry ZIP archive in memory, in insertion order.
*
* Every entry's sizes and CRC-32 are known before it is written, so each local header carries them and
* no data descriptor follows. No extra fields are written, which is what fixes a first stored entry's
* payload at offset 30 plus its name length - the UMA mimetype probe relies on it (docs/format/UMA.md §1).
* Output is a pure function of the entries added and [dosDateTime]: no wall clock, no host attributes.
*
* @param Int dosDateTime The MS-DOS modification stamp every entry carries: date in the high 16 bits,
* time in the low 16 (see ZipRecords.dosDateTimeOf). A parameter rather than a clock read, so the
* caller decides whether archives are byte-reproducible.
*/
internal class ZipWriter(private val dosDateTime: Int) {
/**
* What the central directory needs to repeat about one written entry.
*
* @property ByteArray nameBytes The UTF-8 name.
* @property Int versionNeeded The "version needed to extract".
* @property Int flags The general purpose bit flags.
* @property Int method The compression method.
* @property Long crc32 The CRC-32 of the uncompressed bytes.
* @property Int compressedSize The payload's size.
* @property Int uncompressedSize The uncompressed size.
* @property Int dosDateTime The MS-DOS modification stamp the entry carries.
* @property Long localHeaderOffset Where the entry's local header starts.
*/
private class WrittenEntry(
val nameBytes: ByteArray,
val versionNeeded: Int,
val flags: Int,
val method: Int,
val crc32: Long,
val compressedSize: Int,
val uncompressedSize: Int,
val dosDateTime: Int,
val localHeaderOffset: Long,
)
private val output = Buffer()
private val writtenEntries = ArrayList<WrittenEntry>()
private val writtenNames = HashSet<String>()
private var finished = false
/**
* Adds an entry stored without compression.
*
* @param String name The entry name; a trailing slash makes it a directory entry.
* @param ByteArray contents The entry's bytes.
*/
fun addStored(name: String, contents: ByteArray) {
writeEntry(
name = name,
method = ZipRecords.METHOD_STORED,
flags = ZipRecords.FLAG_UTF8_NAME,
crc32 = crc32Of(contents),
uncompressedSize = contents.size,
payload = contents,
)
}
/**
* Adds an entry compressed with DEFLATE.
*
* @param String name The entry name.
* @param ByteArray contents The entry's uncompressed bytes.
* @param Int level The DEFLATE level, 0..9.
*/
fun addDeflated(name: String, contents: ByteArray, level: Int = DEFAULT_DEFLATE_LEVEL) {
require(level in 0..9) { "DEFLATE level must be in 0..9: $level" }
writeEntry(
name = name,
method = ZipRecords.METHOD_DEFLATED,
flags = ZipRecords.FLAG_UTF8_NAME,
crc32 = crc32Of(contents),
uncompressedSize = contents.size,
payload = deflateRawDeflate(contents, level),
)
}
/**
* Adds an entry copied from another archive without inflating or recompressing it: the method, CRC-32,
* sizes, encryption flag, version needed, and payload bytes carry over verbatim. The name and timestamp are
* this writer's, like every other entry, except where a decryption check depends on them (see below).
*
* An encrypted entry whose source used a data descriptor keeps it, and keeps its source's timestamp: traditional
* PKWARE decryption checks the last byte of the encryption header against the timestamp's high byte when flag
* bit 3 is set, and against the CRC-32's high byte otherwise (APPNOTE.TXT 6.1.6), so changing either would make
* the entry undecryptable.
*
* @param ZipEntry entry The source entry, as its archive declares it.
* @param ByteArray rawPayload The source entry's payload exactly as stored (ZipArchive.rawPayload).
*/
fun addRaw(entry: ZipEntry, rawPayload: ByteArray) {
require(rawPayload.size == entry.compressedSize) {
"entry '${entry.name}' declares ${entry.compressedSize} payload bytes but ${rawPayload.size} were given"
}
addRaw(entry, rawPayload, 0)
}
/**
* Adds an entry copied from another archive, its payload read in place from [source] at [payloadOffset] rather
* than from a copy; see the overload taking the payload alone.
*
* @param ZipEntry entry The source entry, as its archive declares it.
* @param ByteArray source The bytes holding the payload: the source archive, or a copy of the payload.
* @param Int payloadOffset Where the payload starts in [source].
*/
fun addRaw(entry: ZipEntry, source: ByteArray, payloadOffset: Int) {
require(payloadOffset >= 0 && payloadOffset.toLong() + entry.compressedSize <= source.size) {
"entry '${entry.name}' declares ${entry.compressedSize} payload bytes, which its source does not hold at $payloadOffset"
}
val keepsDescriptor = entry.isEncrypted && (entry.flags and ZipRecords.FLAG_DATA_DESCRIPTOR) != 0
// Every other copied entry's sizes sit in its local header, so a data descriptor flag from its source would send
// a reader looking for a record that is not there.
val flags = if (keepsDescriptor) entry.flags or ZipRecords.FLAG_UTF8_NAME else (entry.flags and ZipRecords.FLAG_DATA_DESCRIPTOR.inv()) or ZipRecords.FLAG_UTF8_NAME
writeEntry(
name = entry.name,
method = entry.method,
flags = flags,
crc32 = entry.crc32,
uncompressedSize = entry.uncompressedSize,
payload = source,
payloadOffset = payloadOffset,
payloadSize = entry.compressedSize,
sourceVersionNeeded = entry.versionNeeded,
entryDosDateTime = if (keepsDescriptor) entry.dosDateTime else dosDateTime,
writesDescriptor = keepsDescriptor,
)
}
/**
* Writes the central directory and the end records and returns the archive. The writer takes no
* entries afterward.
*
* Zip64 end records are added only when the entry count reaches 0xFFFF, where the classic 16-bit count
* field runs out (its all-ones value is reserved to mean "see Zip64"). Sizes and offsets cannot
* overflow their 32-bit fields: the archive is a byte array, so it is under 2 GiB by construction.
*
* @return ByteArray The archive.
*/
fun finish(): ByteArray {
check(!finished) { "the archive has already been finished" }
finished = true
val directoryOffset = output.size
for (entry in writtenEntries) {
writeCentralHeader(entry)
}
val directorySize = output.size - directoryOffset
val entryCount = writtenEntries.size
val needsZip64 = entryCount >= ZipRecords.UINT16_SENTINEL
if (needsZip64) {
val zip64EndOffset = output.size
// ZIP: Zip64 end of central directory record (APPNOTE.TXT 4.3.14).
output.writeIntLe(ZipRecords.ZIP64_END_SIGNATURE)
output.writeLongLe(ZipRecords.ZIP64_END_RECORD_REMAINDER.toLong())
output.writeShortLe(ZipRecords.VERSION_ZIP64)
output.writeShortLe(ZipRecords.VERSION_ZIP64)
output.writeIntLe(0)
output.writeIntLe(0)
output.writeLongLe(entryCount.toLong())
output.writeLongLe(entryCount.toLong())
output.writeLongLe(directorySize)
output.writeLongLe(directoryOffset)
// ZIP: Zip64 end of central directory locator (APPNOTE.TXT 4.3.15).
output.writeIntLe(ZipRecords.ZIP64_LOCATOR_SIGNATURE)
output.writeIntLe(0)
output.writeLongLe(zip64EndOffset)
output.writeIntLe(1)
}
val classicCount = if (needsZip64) ZipRecords.UINT16_SENTINEL else entryCount
// ZIP: end of central directory record (APPNOTE.TXT 4.3.16).
output.writeIntLe(ZipRecords.END_SIGNATURE)
output.writeShortLe(0)
output.writeShortLe(0)
output.writeShortLe(classicCount)
output.writeShortLe(classicCount)
output.writeIntLe(directorySize.toInt())
output.writeIntLe(directoryOffset.toInt())
output.writeShortLe(0)
check(output.size <= MAXIMUM_ARCHIVE_SIZE) { "the archive exceeds what a byte array can hold: ${output.size} bytes" }
return output.readByteArray()
}
/**
* Writes one entry's local header and payload, and records what its central header will repeat. Every check runs
* before anything is written or the name is taken, so a refused entry leaves the writer as it was.
*
* @param String name The entry name.
* @param Int method The compression method.
* @param Int flags The general purpose bit flags.
* @param Long crc32 The CRC-32 of the uncompressed bytes.
* @param Int uncompressedSize The uncompressed size.
* @param ByteArray payload The bytes holding the payload.
* @param Int payloadOffset Where the payload starts in [payload].
* @param Int payloadSize The payload's length.
* @param Int sourceVersionNeeded The version needed a copied entry's source declared, or 0.
* @param Int entryDosDateTime The MS-DOS stamp the entry carries.
* @param Boolean writesDescriptor Whether the local header leaves the CRC-32 and sizes zero for a data
* descriptor after the payload (flag bit 3).
*/
private fun writeEntry(
name: String,
method: Int,
flags: Int,
crc32: Long,
uncompressedSize: Int,
payload: ByteArray,
payloadOffset: Int = 0,
payloadSize: Int = payload.size,
sourceVersionNeeded: Int = 0,
entryDosDateTime: Int = dosDateTime,
writesDescriptor: Boolean = false,
) {
check(!finished) { "the archive has already been finished" }
require(name.isNotEmpty()) { "an entry name cannot be empty" }
require(name !in writtenNames) { "the archive already holds an entry named '$name'" }
val nameBytes = name.encodeToByteArray()
require(nameBytes.size <= 0xFFFF) { "entry name '$name' is longer than a ZIP header can hold" }
val descriptorSize = if (writesDescriptor) ZipRecords.DATA_DESCRIPTOR_SIZE else 0
val projectedSize = output.size + ZipRecords.LOCAL_HEADER_SIZE + nameBytes.size + payloadSize + descriptorSize
check(projectedSize <= MAXIMUM_ARCHIVE_SIZE) { "the archive would exceed what a byte array can hold: $projectedSize bytes" }
writtenNames += name
// ZIP: version needed to extract (APPNOTE.TXT 4.4.3) - what this entry's method needs, or what a copied entry's
// source declared when that is more (an AES or other entry this writer never produces itself).
val methodVersion = if (method == ZipRecords.METHOD_STORED) ZipRecords.VERSION_STORED else ZipRecords.VERSION_DEFLATED
val entry =
WrittenEntry(
nameBytes = nameBytes,
versionNeeded = maxOf(methodVersion, sourceVersionNeeded),
flags = flags,
method = method,
crc32 = crc32,
compressedSize = payloadSize,
uncompressedSize = uncompressedSize,
dosDateTime = entryDosDateTime,
localHeaderOffset = output.size,
)
// ZIP: local file header (APPNOTE.TXT 4.3.7).
output.writeIntLe(ZipRecords.LOCAL_HEADER_SIGNATURE)
output.writeShortLe(entry.versionNeeded)
output.writeShortLe(entry.flags)
output.writeShortLe(entry.method)
// ZIP: @ +0x0A time, @ +0x0C date.
output.writeShortLe(entry.dosDateTime and 0xFFFF)
output.writeShortLe((entry.dosDateTime ushr 16) and 0xFFFF)
// ZIP: @ +0x0E crc-32, @ +0x12 compressed size, @ +0x16 uncompressed size - zero when a data descriptor carries
// them (APPNOTE.TXT 4.4.4).
output.writeIntLe(if (writesDescriptor) 0 else entry.crc32.toInt())
output.writeIntLe(if (writesDescriptor) 0 else entry.compressedSize)
output.writeIntLe(if (writesDescriptor) 0 else entry.uncompressedSize)
output.writeShortLe(nameBytes.size)
output.writeShortLe(0)
output.write(nameBytes)
output.write(payload, payloadOffset, payloadSize)
if (writesDescriptor) {
// ZIP: data descriptor (APPNOTE.TXT 4.3.9), with its optional signature.
output.writeIntLe(ZipRecords.DATA_DESCRIPTOR_SIGNATURE)
output.writeIntLe(entry.crc32.toInt())
output.writeIntLe(entry.compressedSize)
output.writeIntLe(entry.uncompressedSize)
}
writtenEntries += entry
}
/**
* Writes one entry's central directory file header.
*
* @param WrittenEntry entry The entry.
*/
private fun writeCentralHeader(entry: WrittenEntry) {
// ZIP: central directory file header (APPNOTE.TXT 4.3.12). "Version made by" is 2.0 on an MS-DOS
// host with zero attributes, so nothing about the machine that wrote the archive leaks into it.
output.writeIntLe(ZipRecords.CENTRAL_HEADER_SIGNATURE)
output.writeShortLe(ZipRecords.VERSION_DEFLATED)
output.writeShortLe(entry.versionNeeded)
output.writeShortLe(entry.flags)
output.writeShortLe(entry.method)
output.writeShortLe(entry.dosDateTime and 0xFFFF)
output.writeShortLe((entry.dosDateTime ushr 16) and 0xFFFF)
output.writeIntLe(entry.crc32.toInt())
output.writeIntLe(entry.compressedSize)
output.writeIntLe(entry.uncompressedSize)
output.writeShortLe(entry.nameBytes.size)
// ZIP: @ +0x1E extra length, @ +0x20 comment length, @ +0x22 disk number start, @ +0x24 internal
// attributes - all zero.
output.writeShortLe(0)
output.writeShortLe(0)
output.writeShortLe(0)
output.writeShortLe(0)
// ZIP: @ +0x26 external attributes, zero.
output.writeIntLe(0)
output.writeIntLe(entry.localHeaderOffset.toInt())
output.write(entry.nameBytes)
}
private companion object {
/** zlib's default level, spelled out so the writer's output never depends on a library default. */
const val DEFAULT_DEFLATE_LEVEL = 6
/** The largest archive a ByteArray can hold on every target. */
const val MAXIMUM_ARCHIVE_SIZE = Int.MAX_VALUE - 8L
/**
* The CRC-32 of [bytes].
*
* @param ByteArray bytes The bytes.
* @return Long The checksum, unsigned.
*/
fun crc32Of(bytes: ByteArray): Long = Crc32().also { crc -> crc.update(bytes) }.value
}
}
@@ -0,0 +1,262 @@
package org.umamo.format.bmp
import okio.Buffer
import org.umamo.format.FileKind
import org.umamo.format.raster.RasterCodec
import org.umamo.format.raster.RasterImage
/**
* Pure-Kotlin BMP codec (desktop JVM and Android), read and write.
*
* Reads uncompressed Windows BMPs - 24-bit BGR and 32-bit BGRA (BI_RGB), and 16/32-bit
* BI_BITFIELDS with explicit channel masks - into the neutral straight-alpha RGBA8888 top-first
* [RasterImage]. Writes a 32-bit BITMAPV4HEADER file with explicit RGBA channel masks so straight
* alpha round-trips losslessly. Palette (<= 8-bit) and RLE BMPs are out of scope and rejected.
* Trivial and dependency-free, so it doubles as a debug-dump and round-trip test vehicle.
*/
public object BmpCodec : RasterCodec {
override val kind: FileKind = FileKind.Bmp
// BMP: compression codes (wingdi.h BI_*).
private const val BI_RGB = 0
private const val BI_BITFIELDS = 3
private const val BI_ALPHABITFIELDS = 6
private const val FILE_HEADER_SIZE = 14
private const val V4_HEADER_SIZE = 108
private const val OPAQUE = 0xFF.toByte()
/**
* True if [candidateBytes] opens with the "BM" signature.
*
* @param ByteArray candidateBytes Candidate file contents.
* @return Boolean Whether the leading bytes are the BMP magic.
*/
override fun matches(candidateBytes: ByteArray): Boolean =
// BMP: BITMAPFILEHEADER.bfType @ +0x00 = 'B','M'.
candidateBytes.size >= 2 && candidateBytes[0] == 0x42.toByte() && candidateBytes[1] == 0x4D.toByte()
/**
* Decodes a `.bmp` into a straight-alpha RGBA8888 [RasterImage], top row first.
*
* @param ByteArray bytes The complete `.bmp` file.
* @return RasterImage The decoded image.
*/
override fun read(bytes: ByteArray): RasterImage {
require(matches(bytes)) { "Not a BMP (bad signature)" }
require(bytes.size >= FILE_HEADER_SIZE + 40) { "BMP too short for a DIB header" }
// BMP: BITMAPFILEHEADER.bfOffBits @ +0x0A - offset of the pixel array.
val pixelOffset = readU32LE(bytes, 10).toInt()
// BMP: BITMAPINFOHEADER @ +0x0E - biSize, biWidth, biHeight, biPlanes, biBitCount, biCompression.
val dibStart = FILE_HEADER_SIZE
val dibSize = readU32LE(bytes, dibStart).toInt()
require(dibSize >= 40) { "Insupported BMP DIB header size $dibSize (Need BITMAPINFOHEADER or later)" }
val width = readI32LE(bytes, dibStart + 4)
val rawHeight = readI32LE(bytes, dibStart + 8)
val bitCount = readU16LE(bytes, dibStart + 14)
val compression = readU32LE(bytes, dibStart + 16).toInt()
require(width > 0 && rawHeight != 0) { "BMP has non-positive width or zero height" }
val height = kotlin.math.abs(rawHeight)
val topDown = rawHeight < 0 // BMP: a negative biHeight means the rows are stored top-to-bottom.
require(bitCount == 16 || bitCount == 24 || bitCount == 32) {
"Unsupported BMP bit count $bitCount (only uncompressed 16/24/32-bit; palette/RLE rejected)"
}
require(compression == BI_RGB || compression == BI_BITFIELDS || compression == BI_ALPHABITFIELDS) {
"Unsupported BMP compression $compression (only BI_RGB / BI_BITFIELDS)"
}
val masks = resolveMasks(bytes, dibStart, dibSize, bitCount, compression)
val rowStride = ((bitCount * width + 31) / 32) * 4
val rgba = ByteArray(width * height * 4)
for (fileRow in 0 until height) {
val rowStart = pixelOffset + fileRow * rowStride
// Bottom-up storage (positive height) puts file row 0 at the image bottom; flip to top-first.
val imageRow = if (topDown) fileRow else (height - 1 - fileRow)
for (column in 0 until width) {
val destination = (imageRow * width + column) * 4
when (bitCount) {
24 -> {
// BMP: 24-bit BI_RGB pixels are stored B, G, R (no alpha).
val pixel = rowStart + column * 3
if (pixel + 2 < bytes.size) {
rgba[destination] = bytes[pixel + 2]
rgba[destination + 1] = bytes[pixel + 1]
rgba[destination + 2] = bytes[pixel]
}
rgba[destination + 3] = OPAQUE
}
else -> {
val pixel = rowStart + column * (bitCount / 8)
val value =
if (bitCount == 32) {
if (pixel + 3 < bytes.size) readU32LE(bytes, pixel).toInt() else 0
} else {
if (pixel + 1 < bytes.size) readU16LE(bytes, pixel) else 0
}
rgba[destination] = extractChannel(value, masks.red).toByte()
rgba[destination + 1] = extractChannel(value, masks.green).toByte()
rgba[destination + 2] = extractChannel(value, masks.blue).toByte()
rgba[destination + 3] = if (masks.alpha == 0) OPAQUE else extractChannel(value, masks.alpha).toByte()
}
}
}
}
return RasterImage(width, height, rgba)
}
/**
* Encodes a [RasterImage] as a 32-bit BGRA BMP with a BITMAPV4HEADER carrying explicit channel
* masks (including alpha), stored bottom-up. Straight alpha round-trips losslessly.
*
* @param RasterImage model The image to encode.
* @return ByteArray The complete `.bmp` file.
*/
override fun write(model: RasterImage): ByteArray {
val rowStride = model.width * 4 // 32-bit rows are already 4-byte aligned.
val pixelDataSize = rowStride * model.height
val pixelOffset = FILE_HEADER_SIZE + V4_HEADER_SIZE
val fileSize = pixelOffset + pixelDataSize
val out = Buffer()
// BITMAPFILEHEADER.
out.writeByte(0x42)
out.writeByte(0x4D)
out.writeIntLe(fileSize)
out.writeShortLe(0) // bfReserved1
out.writeShortLe(0) // bfReserved2
out.writeIntLe(pixelOffset) // bfOffBits
// BITMAPV4HEADER.
out.writeIntLe(V4_HEADER_SIZE)
out.writeIntLe(model.width)
out.writeIntLe(model.height) // positive: bottom-up
out.writeShortLe(1) // planes
out.writeShortLe(32) // bitCount
out.writeIntLe(BI_BITFIELDS)
out.writeIntLe(pixelDataSize)
out.writeIntLe(2835) // xPelsPerMeter (~72 DPI)
out.writeIntLe(2835) // yPelsPerMeter
out.writeIntLe(0) // clrUsed
out.writeIntLe(0) // clrImportant
out.writeIntLe(0x00FF0000) // redMask
out.writeIntLe(0x0000FF00) // greenMask
out.writeIntLe(0x000000FF) // blueMask
out.writeIntLe(-0x1000000) // alphaMask 0xFF000000
out.writeIntLe(0x73524742) // CSType 'sRGB'
repeat(9) { out.writeIntLe(0) } // CIEXYZTRIPLE endpoints (ignored for BI_BITFIELDS)
out.writeIntLe(0) // gammaRed
out.writeIntLe(0) // gammaGreen
out.writeIntLe(0) // gammaBlue
// Pixel array, bottom-up: file row 0 is the image's bottom row. Each pixel is B, G, R, A.
for (fileRow in 0 until model.height) {
val imageRow = model.height - 1 - fileRow
var source = imageRow * rowStride
for (column in 0 until model.width) {
out.writeByte(model.rgba[source + 2].toInt() and 0xFF) // B
out.writeByte(model.rgba[source + 1].toInt() and 0xFF) // G
out.writeByte(model.rgba[source].toInt() and 0xFF) // R
out.writeByte(model.rgba[source + 3].toInt() and 0xFF) // A
source += 4
}
}
return out.readByteArray()
}
/** The four channel bit-masks a BI_BITFIELDS (or defaulted BI_RGB) BMP uses. */
private class ChannelMasks(val red: Int, val green: Int, val blue: Int, val alpha: Int)
/**
* Resolves the per-channel bit masks: explicit ones for BI_BITFIELDS (from the V4+ header, or the
* DWORDs after a 40-byte BITMAPINFOHEADER), else the format defaults for BI_RGB.
*
* @param ByteArray bytes The complete file.
* @param Int dibStart Offset of the DIB header.
* @param Int dibSize DIB header size in bytes.
* @param Int bitCount Bits per pixel (16 or 32 here).
* @param Int compression The BMP compression code.
* @return ChannelMasks The resolved masks (alpha = 0 means "no alpha, treat as opaque").
*/
private fun resolveMasks(bytes: ByteArray, dibStart: Int, dibSize: Int, bitCount: Int, compression: Int): ChannelMasks {
if (compression == BI_BITFIELDS || compression == BI_ALPHABITFIELDS) {
// The masks sit at the same place either way: inside a V4/V5 header at +40, or as the DWORDs
// immediately following a bare 40-byte BITMAPINFOHEADER (which bfOffBits skips past).
val maskBase = dibStart + 40
val red = readU32LE(bytes, maskBase).toInt()
val green = readU32LE(bytes, maskBase + 4).toInt()
val blue = readU32LE(bytes, maskBase + 8).toInt()
val alpha =
if (compression == BI_ALPHABITFIELDS || dibSize >= 56) {
readU32LE(bytes, maskBase + 12).toInt()
} else {
0
}
return ChannelMasks(red, green, blue, alpha)
}
// BI_RGB defaults: 32-bit is X8R8G8B8 (alpha unused → opaque); 16-bit is X1R5G5B5.
return if (bitCount == 32) {
ChannelMasks(0x00FF0000, 0x0000FF00, 0x000000FF, 0)
} else {
ChannelMasks(0x7C00, 0x03E0, 0x001F, 0)
}
}
/**
* Extracts one channel from a packed pixel value via its mask, scaled to 8 bits.
*
* @param Int value The packed little-endian pixel value.
* @param Int mask The channel bit mask (0 → returns 255, the opaque default for a missing channel).
* @return Int The channel value in 0..255.
*/
private fun extractChannel(value: Int, mask: Int): Int {
if (mask == 0) {
return 0xFF
}
val shift = mask.countTrailingZeroBits()
val bits = mask.countOneBits()
val raw = (value ushr shift) and ((1 shl bits) - 1)
val maxValue = (1 shl bits) - 1
return if (bits == 8) raw else (raw * 255 + maxValue / 2) / maxValue
}
/**
* Reads a little-endian unsigned 16-bit value.
*
* @param ByteArray bytes The buffer.
* @param Int at Offset of the least-significant byte.
* @return Int The value in 0..65535.
*/
private fun readU16LE(bytes: ByteArray, at: Int): Int =
(bytes[at].toInt() and 0xFF) or ((bytes[at + 1].toInt() and 0xFF) shl 8)
/**
* Reads a little-endian unsigned 32-bit value as a Long.
*
* @param ByteArray bytes The buffer.
* @param Int at Offset of the least-significant byte.
* @return Long The value in 0..4294967295.
*/
private fun readU32LE(bytes: ByteArray, at: Int): Long =
(bytes[at].toLong() and 0xFF) or
((bytes[at + 1].toLong() and 0xFF) shl 8) or
((bytes[at + 2].toLong() and 0xFF) shl 16) or
((bytes[at + 3].toLong() and 0xFF) shl 24)
/**
* Reads a little-endian signed 32-bit value (BMP width/height are signed).
*
* @param ByteArray bytes The buffer.
* @param Int at Offset of the least-significant byte.
* @return Int The signed value.
*/
private fun readI32LE(bytes: ByteArray, at: Int): Int =
(bytes[at].toInt() and 0xFF) or
((bytes[at + 1].toInt() and 0xFF) shl 8) or
((bytes[at + 2].toInt() and 0xFF) shl 16) or
((bytes[at + 3].toInt() and 0xFF) shl 24)
}
@@ -0,0 +1,55 @@
package org.umamo.format.clip
import org.umamo.format.art.LayerBlend
/**
* Maps a CLIP `Layer.LayerComposite` blend-mode code to the neutral [LayerBlend].
*
* EN: The complete enum was reverse-engineered from LayerBlendModes.clip (one layer per mode, named
* after the Clip Studio Paint UI label). Codes are contiguous 0..26, then 36 for Divide; the
* 27..35 gap is unused for leaf layers. Code 30 was observed only on folders in one sample
* and is the folder pass-through composite, not a leaf blend mode - it is not represented here
* (folders are not emitted as layers). Truly unknown codes degrade to Normal.
* JA: LayerComposite コードを中立 LayerBlend へ写像する. LayerBlendModes.clip から全列挙を判明.
*/
object ClipBlend {
/**
* Returns the neutral blend mode for a LayerComposite code, defaulting unknown codes to Normal.
*
* @param Long compositeCode The raw Layer.LayerComposite value.
* @return LayerBlend The mapped blend mode (Normal for any unrecognized code).
*/
fun fromCompositeCode(compositeCode: Long): LayerBlend =
// CLIP: Layer.LayerComposite - verified code table (see LayerBlendModes.clip / docs/CLIP.md §3).
when (compositeCode) {
0L -> LayerBlend.Normal
1L -> LayerBlend.Darken
2L -> LayerBlend.Multiply
3L -> LayerBlend.ColorBurn
4L -> LayerBlend.LinearBurn
5L -> LayerBlend.Subtract
6L -> LayerBlend.DarkerColor
7L -> LayerBlend.Lighten
8L -> LayerBlend.Screen
9L -> LayerBlend.ColorDodge
10L -> LayerBlend.GlowDodge
11L -> LayerBlend.Add
12L -> LayerBlend.AddGlow
13L -> LayerBlend.LighterColor
14L -> LayerBlend.Overlay
15L -> LayerBlend.SoftLight
16L -> LayerBlend.HardLight
17L -> LayerBlend.VividLight
18L -> LayerBlend.LinearLight
19L -> LayerBlend.PinLight
20L -> LayerBlend.HardMix
21L -> LayerBlend.Difference
22L -> LayerBlend.Exclusion
23L -> LayerBlend.Hue
24L -> LayerBlend.Saturation
25L -> LayerBlend.Color
26L -> LayerBlend.Luminosity // CLIP: CSP UI label "Brightness".
36L -> LayerBlend.Divide
else -> LayerBlend.Normal // includes folder code 30 (pass-through) and the unused 27..35 gap.
}
}
@@ -0,0 +1,133 @@
package org.umamo.format.clip
import org.umamo.format.binary.decodeAscii
/**
* Parser for the outer CLIP (Clip Studio Paint) container: the CSFCHUNK wrapper.
*
* EN: A .clip file is a flat sequence of 8-byte-ASCII-tagged chunks with big-endian u64 sizes,
* verified against several samples(`>8sQ`). This object walks that sequence and hands back
* the embedded SQLite database (the CHNKSQLi payload), which carries the layer table the
* reader needs. The tiled raster in the CHNKExta chunks is left untouched.
* JA: CLIP コンテナ(CSFCHUNK)を解析し, 埋め込み SQLite(CHNKSQLi)を取り出す.
*
* Layout (all integers big-endian):
* // CLIP: @ +0x00 "CSFCHUNK" (8) container magic
* // CLIP: @ +0x08 fileSize u64 whole-file length
* // CLIP: @ +0x10 headOffset u64 offset of the first chunk (= 24)
* // CLIP: then [8-byte id][u64 size][size bytes payload] repeated:
* // "CHNKHead" header · "CHNKExta" external raster · "CHNKSQLi" db · "CHNKFoot" terminator
*/
object ClipContainer {
/** Container magic at offset 0. */
internal const val MAGIC = "CSFCHUNK"
private const val CHUNK_SQLITE = "CHNKSQLi"
private const val CHUNK_FOOTER = "CHNKFoot"
// An 8-byte ASCII id + an 8-byte big-endian u64 size precede every chunk payload.
private const val CHUNK_HEADER_SIZE = 16
/**
* True if [candidateBytes] begins with the CSFCHUNK container magic.
*
* @param ByteArray candidateBytes Candidate file contents.
* @return Boolean Whether the leading bytes are the CLIP magic.
*/
fun isClip(candidateBytes: ByteArray): Boolean {
// CLIP: CSFCHUNK container magic @ +0x00.
val magic = MAGIC.encodeToByteArray()
if (candidateBytes.size < magic.size) {
return false
}
for (magicIndex in magic.indices) {
if (candidateBytes[magicIndex] != magic[magicIndex]) {
return false
}
}
return true
}
/**
* Extracts the embedded SQLite database (the CHNKSQLi chunk payload) from a complete .clip file.
*
* Walks the chunk sequence from the header offset, returning the byte slice of the first
* CHNKSQLi payload. Stops at CHNKFoot. The returned array is a fresh copy, safe to write to a
* temp file for the SQLite driver.
*
* @param ByteArray bytes The complete .clip file contents.
* @return ByteArray The raw "SQLite format 3" database bytes.
* @throws IllegalArgumentException If the magic is missing or no CHNKSQLi chunk is present.
*/
fun extractSqliteDatabase(bytes: ByteArray): ByteArray {
require(isClip(bytes)) { "not a .clip file: missing CSFCHUNK magic @ +0x00" }
// CLIP: @ +0x10 headOffset u64 - where the first chunk begins (24 in every observed file).
val headOffset = readUInt64(bytes, 16)
var offset = requireFits(headOffset, "headOffset")
while (offset + CHUNK_HEADER_SIZE <= bytes.size) {
val chunkId = readAscii(bytes, offset, 8)
// CLIP: chunk size u64 immediately after the 8-byte id.
val payloadSize = requireFits(readUInt64(bytes, offset + 8), "chunk '$chunkId' size")
val payloadStart = offset + CHUNK_HEADER_SIZE
if (chunkId == CHUNK_SQLITE) {
val payloadEnd = payloadStart + payloadSize
require(payloadEnd <= bytes.size) {
"CHNKSQLi payload runs past EOF (need $payloadEnd, have ${bytes.size})"
}
return bytes.copyOfRange(payloadStart, payloadEnd)
}
if (chunkId == CHUNK_FOOTER) {
break
}
offset = payloadStart + payloadSize
}
throw IllegalArgumentException("no CHNKSQLi chunk found in the CLIP container")
}
/**
* Reads a big-endian unsigned 64-bit integer as a Long.
*
* @param ByteArray bytes The buffer to read from.
* @param Int at The offset of the most-significant byte.
* @return Long The decoded value (treated as non-negative; CLIP sizes never use the sign bit).
*/
private fun readUInt64(bytes: ByteArray, at: Int): Long {
require(at + 8 <= bytes.size) { "truncated u64 @ +$at" }
var value = 0L
for (byteIndex in 0 until 8) {
value = (value shl 8) or (bytes[at + byteIndex].toLong() and 0xFF)
}
return value
}
/**
* Reads a fixed-length ASCII string (chunk ids are 8-byte ASCII tags).
*
* @param ByteArray bytes The buffer to read from.
* @param Int at The start offset.
* @param Int length The number of bytes to read.
* @return String The decoded ASCII string.
*/
private fun readAscii(bytes: ByteArray, at: Int, length: Int): String {
require(at + length <= bytes.size) { "truncated ascii @ +$at" }
return decodeAscii(bytes, at, length)
}
/**
* Narrows a 64-bit file offset/size to an Int, since the whole file is held in one ByteArray
* (so any valid offset fits). Rejects values that would overflow rather than silently wrapping.
*
* @param Long value The 64-bit value to narrow.
* @param String label A description used in the error message.
* @return Int The value as a non-negative Int.
*/
private fun requireFits(value: Long, label: String): Int {
require(value in 0..Int.MAX_VALUE) { "$label out of addressable range: $value" }
return value.toInt()
}
}
@@ -0,0 +1,18 @@
package org.umamo.format.clip
import org.umamo.format.clip.db.ClipDatabase
/**
* Opens a SQLDelight driver over the extracted .clip SQLite [databaseBytes], runs [block] against the
* resulting [ClipDatabase], and tears the driver (and any temp file) down afterward.
*
* The driver is the only platform-specific piece - JVM uses JdbcSqliteDriver, Android uses
* AndroidSqliteDriver - so it lives behind this expect/actual seam while the rest of the reader stays
* platform-neutral. The embedded database already has its tables, so the actuals must NOT run
* Schema.create.
*
* @param ByteArray databaseBytes The raw "SQLite format 3" bytes (the CHNKSQLi payload).
* @param Function1 block Runs against the open database and returns the parsed result.
* @return T The block's result.
*/
internal expect fun <T> useClipDatabase(databaseBytes: ByteArray, block: (ClipDatabase) -> T): T
@@ -0,0 +1,268 @@
package org.umamo.format.clip
import org.umamo.format.art.LayerBlend
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.LayerId
import org.umamo.format.art.LayerRaster
import org.umamo.format.art.SourceArt
import org.umamo.format.art.SourceGroup
import org.umamo.format.art.SourceLayer
import org.umamo.format.art.SourceLayerKind
/**
* Document geometry plus the id of the root folder the layer walk descends from.
*
* Decoupled from the SQLDelight-generated row types so the tree logic is pure and testable; the
* reader maps the generated Canvas row into this.
*/
internal data class ClipCanvas(
val widthPx: Int,
val heightPx: Int,
val rootFolderId: Long,
)
/**
* One CLIP Layer row, reduced to the fields the neutral model needs and with nulls already
* defaulted. The reader maps each SQLDelight-generated row into this shape.
*/
internal data class ClipLayerRow(
val mainId: Long,
val name: String,
val folder: Long,
val type: Long,
val visibility: Long,
val opacity: Long,
val composite: Long,
val clip: Long,
val offsetX: Long,
val offsetY: Long,
val firstChildIndex: Long,
val nextIndex: Long,
val uuid: String?,
// Tile-grid anchor = (offsetX + renderOffscrX, offsetY + renderOffscrY); canvas-aligned (0 in corpus).
val renderOffscrX: Long,
val renderOffscrY: Long,
)
// CLIP: Layer.LayerFolder bit 0x10 marks a folder/group node.
private const val LAYER_FOLDER_BIT = 0x10L
// CLIP: Layer.LayerOpacity is a 0..256 fixed-point scale (256 == fully opaque), not 0..255.
private const val OPACITY_FULL = 256f
// CLIP: Layer.LayerVisibility is a bitfield; bit 0 is "shown" (values 1 and 3 are visible, 2 hidden -
// verified by several samples). The other bit is an unrelated sub-flag.
private const val VISIBILITY_SHOWN_BIT = 1L
// CLIP: Layer.LayerComposite == 30 is the folder "Through" (pass-through, non-isolating) mode - the
// default for a new folder. Only meaningful on folder rows; observed in several samples.
private const val COMPOSITE_THROUGH = 30L
// CLIP: Layer.LayerType - verified across the corpus (see docs/CLIP.md §5). 1 and 3 are raster
// layers (pixels persist); 0 is an object layer (vector/text, distinguished by TextLayerType); 1584
// is the Paper/fill layer; 4098 is a procedural adjustment/correction layer. None of 0/1584/4098
// carry a persisted raster.
private const val LAYER_TYPE_RASTER_PLAIN = 1L
private const val LAYER_TYPE_RASTER_VARIANT = 3L
private const val LAYER_TYPE_OBJECT = 0L
private const val LAYER_TYPE_FILL = 1584L
private const val LAYER_TYPE_ADJUSTMENT = 4098L
/**
* Classifies a leaf layer row into a neutral [SourceLayerKind].
*
* @param ClipLayerRow row The leaf layer row.
* @param Set textLayerIds MainIds of text object layers (empty on schemas without TextLayerType).
* @return SourceLayerKind The layer kind (Raster unless it is an object/fill/adjustment layer).
*/
private fun layerKindOf(row: ClipLayerRow, textLayerIds: Set<Long>): SourceLayerKind =
when (row.type) {
LAYER_TYPE_RASTER_PLAIN, LAYER_TYPE_RASTER_VARIANT -> SourceLayerKind.Raster
// CLIP: a text layer is in textLayerIds (TextLayerType set); other object layers are vector.
LAYER_TYPE_OBJECT -> if (row.mainId in textLayerIds) SourceLayerKind.Text else SourceLayerKind.Vector
LAYER_TYPE_FILL -> SourceLayerKind.Fill
LAYER_TYPE_ADJUSTMENT -> SourceLayerKind.Adjustment
else -> SourceLayerKind.Unknown
}
/**
* Builds the neutral, ordered [SourceLayer] list from the CLIP layer table.
*
* EN: The layer tree is encoded as MainId links: a node's LayerFirstChildIndex points at its first
* child and LayerNextIndex at its next sibling (0 terminates each chain). We descend from
* Canvas.CanvasRootFolder (a synthetic root that is never emitted) and flatten depth-first. The
* firstChild/nextSibling walk visits the bottom-most layer first (verified: the root's first
* child in the corpus is "Paper", Clip Studio's default background), so the produced list is
* bottom-to-top - the painter's-algorithm order the compositor expects, matching the KRA reader.
* Folders contribute only their name to the slash-joined groupPath; only leaf layers are emitted.
* JA: MainId のリンク(FirstChild/NextSibling)でツリーを深さ優先に平坦化し, 下から上の順で葉のみ出力する.
*
* @param ClipCanvas canvas The document geometry and root-folder id.
* @param List rows All layer rows (in any order; indexed internally by MainId).
* @param Map rastersByMainId Decoded rasters keyed by layer MainId; absent => placeholder.
* @param Set textLayerIds MainIds of text object layers (for kind classification).
* @return ClipTree The leaf layers (bottom-to-top, order = top-most-first) and the folder groups.
*/
internal fun buildSourceTree(
canvas: ClipCanvas,
rows: List<ClipLayerRow>,
rastersByMainId: Map<Long, ClipDecodedRaster>,
textLayerIds: Set<Long>,
): ClipTree {
val rowsByMainId = rows.associateBy { row -> row.mainId }
val leavesBottomToTop = ArrayList<ClipLeaf>()
val groups = ArrayList<SourceGroup>()
val rootRow = rowsByMainId[canvas.rootFolderId]
if (rootRow != null) {
collectTree(rootRow.firstChildIndex, rowsByMainId, parentPath = "", visited = HashSet(), outLeaves = leavesBottomToTop, outGroups = groups)
}
// SourceLayer.order is top-most-first (0 == topmost); the list itself stays bottom-to-top, so the
// top-most leaf is the last collected. Convert the bottom-up index into a top-down order value.
val lastIndex = leavesBottomToTop.size - 1
val layers =
leavesBottomToTop.mapIndexed { indexFromBottom, leaf ->
toSourceLayer(
row = leaf.row,
groupPath = leaf.groupPath,
order = lastIndex - indexFromBottom,
raster = rastersByMainId[leaf.row.mainId],
textLayerIds = textLayerIds,
)
}
return ClipTree(layers = layers, groups = groups)
}
/** The flattened result of a layer-tree walk: the leaf layers and the folders that enclose them. */
internal class ClipTree(val layers: List<SourceLayer>, val groups: List<SourceGroup>)
/** A leaf layer paired with the slash-joined path of the folders enclosing it. */
private class ClipLeaf(val row: ClipLayerRow, val groupPath: String)
/**
* Walks a sibling chain starting at [startMainId], descending into folders. Leaf layers are
* appended to [outLeaves] in document (bottom-to-top) order; each folder is recorded in [outGroups].
*
* @param Long startMainId MainId of the first sibling (0 terminates immediately).
* @param Map rowsByMainId All rows indexed by MainId.
* @param String parentPath Slash-joined names of the enclosing folders (empty at root).
* @param MutableSet visited Guards against a malformed cyclic link list.
* @param MutableList outLeaves Accumulates leaves in walk order.
* @param MutableList outGroups Accumulates folder groups.
*/
private fun collectTree(
startMainId: Long,
rowsByMainId: Map<Long, ClipLayerRow>,
parentPath: String,
visited: MutableSet<Long>,
outLeaves: MutableList<ClipLeaf>,
outGroups: MutableList<SourceGroup>,
) {
var currentMainId = startMainId
while (currentMainId != 0L) {
if (!visited.add(currentMainId)) {
// A cyclic LayerNextIndex would otherwise loop forever; stop defensively.
break
}
val row = rowsByMainId[currentMainId] ?: break
// CLIP: a node is a group if the folder bit is set; treat "has children" as a group too, so a
// folder whose bit we misread still recurses rather than being emitted as a bogus drawable.
val isGroup = (row.folder and LAYER_FOLDER_BIT) != 0L || row.firstChildIndex != 0L
if (isGroup) {
val childPath = if (parentPath.isEmpty()) row.name else "$parentPath/${row.name}"
outGroups.add(toSourceGroup(row, childPath))
collectTree(row.firstChildIndex, rowsByMainId, childPath, visited, outLeaves, outGroups)
} else {
outLeaves.add(ClipLeaf(row, parentPath))
}
currentMainId = row.nextIndex
}
}
/**
* Converts one folder row into a neutral [SourceGroup].
*
* @param ClipLayerRow row The folder layer row.
* @param String path The slash-joined folder path (including this folder's name).
* @return SourceGroup The neutral folder descriptor.
*/
private fun toSourceGroup(row: ClipLayerRow, path: String): SourceGroup =
ClipSourceGroup(
path = path,
name = row.name,
visible = (row.visibility and VISIBILITY_SHOWN_BIT) != 0L,
opacity = (row.opacity.toFloat() / OPACITY_FULL).coerceIn(0f, 1f),
clipped = row.clip != 0L,
// CLIP: a folder's blend lives in LayerComposite, same codes as a layer; 30 is "Through".
blend = ClipBlend.fromCompositeCode(row.composite),
passThrough = row.composite == COMPOSITE_THROUGH,
)
/**
* Converts one leaf CLIP layer into a neutral [SourceLayer], using its decoded raster when present
* and a transparent 1x1 placeholder otherwise (adjustment/procedural layers carry no own pixels).
*
* @param ClipLayerRow row The leaf layer row.
* @param String groupPath The slash-joined enclosing-folder path.
* @param Int order Draw order, top-most == 0.
* @param ClipDecodedRaster? raster The decoded raster, or null for a transparent placeholder.
* @param Set textLayerIds MainIds of text object layers (for kind classification).
* @return SourceLayer The neutral layer.
*/
private fun toSourceLayer(row: ClipLayerRow, groupPath: String, order: Int, raster: ClipDecodedRaster?, textLayerIds: Set<Long>): SourceLayer {
// CLIP: LayerUuid is rename/reorder-stable - the strongest re-import key; fall back to the
// numeric MainId only if a layer somehow lacks a uuid.
val stableId = row.uuid?.takeIf { uuid -> uuid.isNotBlank() } ?: row.mainId.toString()
// Decoded raster supplies real bounds; otherwise a 1x1 transparent placeholder at the layer
// offset keeps downstream dimensions valid (mirrors the KRA reader's empty-layer placeholder).
val bounds = raster?.bounds ?: LayerBounds(left = row.offsetX.toInt(), top = row.offsetY.toInt(), width = 1, height = 1)
val pixels = raster?.raster ?: LayerRaster(width = 1, height = 1, rgba = ByteArray(4))
return ClipSourceLayer(
id = LayerId(stableId),
name = row.name,
kind = layerKindOf(row, textLayerIds),
visible = (row.visibility and VISIBILITY_SHOWN_BIT) != 0L,
groupPath = groupPath,
order = order,
bounds = bounds,
opacity = (row.opacity.toFloat() / OPACITY_FULL).coerceIn(0f, 1f),
clipped = row.clip != 0L, // CLIP: Layer.LayerClip non-zero == clip to the layer below.
blend = ClipBlend.fromCompositeCode(row.composite),
raster = pixels,
)
}
/** Concrete [SourceLayer] backing a parsed CLIP layer. */
private data class ClipSourceLayer(
override val id: LayerId,
override val name: String,
override val kind: SourceLayerKind,
override val visible: Boolean,
override val groupPath: String,
override val order: Int,
override val bounds: LayerBounds,
override val opacity: Float,
override val clipped: Boolean,
override val blend: LayerBlend,
override val raster: LayerRaster,
) : SourceLayer
/** Concrete [SourceGroup] backing a parsed CLIP folder. */
private data class ClipSourceGroup(
override val path: String,
override val name: String,
override val visible: Boolean,
override val opacity: Float,
override val clipped: Boolean,
override val blend: LayerBlend,
override val passThrough: Boolean,
) : SourceGroup
/** Concrete [SourceArt] backing a parsed CLIP document. */
data class ClipSourceArt(
override val widthPx: Int,
override val heightPx: Int,
override val layers: List<SourceLayer>,
override val groups: List<SourceGroup>,
) : SourceArt
@@ -0,0 +1,503 @@
package org.umamo.format.clip
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.LayerRaster
import org.umamo.format.binary.encodeUtf16Be
import org.umamo.format.binary.inflateZlib
/**
* Decodes a CLIP layer's tiled raster into a cropped RGBA8888 buffer.
*
* EN: A layer's pixels live in an external CHNKExta chunk as a grid of 256x256 tiles. Each tile is
* `[4-byte little-endian length][zlib stream]`; the inflated tile is `2562565` bytes laid out
* as a one-byte alpha plane followed by an interleaved BGRA color plane (the color plane's own
* alpha slot is unused). The tile grid (columns/rows and the padded image size) comes from the
* Offscreen.Attribute index. This object walks the block data, inflates each non-empty tile,
* converts planes to straight-alpha RGBA, and assembles the tiles cropped to their bounding box.
* JA: レイヤーのラスタは 256x256 タイル(4バイト長 + zlib, 展開後はアルファ面 + BGRA 面). 復号して結合する.
*/
internal object ClipRaster {
private const val TILE = 256
private const val TILE_PIXELS = TILE * TILE // 65536 - the 8-bit alpha-plane byte count.
// Every tile is an 8-bit/1-bit alpha plane FIRST, then a color plane. The inflated byte count
// identifies the canvas color mode (all corpus samples have CanvasChannelBytes = 1 / 8-bit):
// RGBA alpha(8b) + BGRA(4x8b) = 5 * TILE_PIXELS (ChannelOrder 33)
// Greyscale alpha(8b) + gray(8b) = 2 * TILE_PIXELS (ChannelOrder 17, ColorType 1)
// Monochrome alpha(1b) + value(1b) = TILE_PIXELS / 4 (ChannelOrder 17, ColorType 2)
private const val RGBA_TILE_BYTES = TILE_PIXELS * 5 // 327680
private const val GREYSCALE_TILE_BYTES = TILE_PIXELS * 2 // 131072
private const val MONOCHROME_TILE_BYTES = TILE_PIXELS / 4 // 16384 (two 1-bit planes, MSB-first)
// One 1-bit plane is TILE_PIXELS/8 bytes; the monochrome value plane follows the alpha plane.
private const val MONOCHROME_PLANE_BYTES = TILE_PIXELS / 8 // 8192
// Generous inflate ceiling so a malformed/other-format tile can't overrun (8 bytes/pixel max).
private const val MAX_TILE_BYTES = TILE_PIXELS * 8
/** The pixel layout of a tile, identified by its inflated byte count. */
private enum class TileFormat { Rgba, Greyscale, Monochrome }
/**
* Maps an inflated tile byte count to its [TileFormat], or null for an unrecognized layout.
*
* @param Int inflatedLength The number of inflated tile bytes.
* @return TileFormat The pixel layout, or null if unsupported.
*/
private fun tileFormatFor(inflatedLength: Int): TileFormat? =
when (inflatedLength) {
RGBA_TILE_BYTES -> TileFormat.Rgba
GREYSCALE_TILE_BYTES -> TileFormat.Greyscale
MONOCHROME_TILE_BYTES -> TileFormat.Monochrome
else -> null
}
// Block-data string tags (UTF-16BE) and the marker for "is the 2nd u32 the start of a tag".
private val BEGIN_TAG = encodeUtf16Be("BlockDataBeginChunk")
private val END_TAG = encodeUtf16Be("BlockDataEndChunk")
private val STATUS_TAG = encodeUtf16Be("BlockStatus")
private val CHECKSUM_TAG = encodeUtf16Be("BlockCheckSum")
// "\x00B\x00l" - the first two UTF-16BE code units shared by every Block* tag; if the 2nd u32
// equals this, the first u32 was the string length (no leading size word).
private const val TAG_PREFIX = 0x0042006CL
private const val CHUNK_HEADER_SIZE = 16 // 8-byte id + u64 size
private const val EXTERNAL_HEADER_SIZE = 56 // CHNKExta payload header: u64 + 40-byte id + u64
/**
* Decodes one layer's raster (optionally baking in its grayscale mask), or returns null when
* there is no decodable content (no non-empty tiles, an unparseable Attribute, or an unexpected
* pixel format) so the caller can fall back to a placeholder.
*
* The mask, when present, modulates alpha: `outputAlpha = colorAlpha * mask / 255`. Mask tiles
* align with color tiles by `(col, row)` - both offscreens are canvas-anchored identically - so a
* color tile with no co-located mask tile is left fully visible (the mask InitColor is 255).
*
* @param ByteArray fileBytes The complete .clip file (chunks are read from it).
* @param Int colorChunkOffset Absolute file offset of the layer's color CHNKExta chunk.
* @param ByteArray colorAttribute The color Offscreen.Attribute tile index.
* @param Int maskChunkOffset Absolute file offset of the mask CHNKExta chunk, or -1 if none.
* @param ByteArray maskAttribute The mask Offscreen.Attribute, or null if the layer has no mask.
* @param Int anchorX Canvas X of tile column 0 (LayerOffsetX + LayerRenderOffscrOffsetX).
* @param Int anchorY Canvas Y of tile row 0.
* @return ClipDecodedRaster The placed, cropped RGBA raster, or null if nothing decodable.
*/
fun decodeLayer(
fileBytes: ByteArray,
colorChunkOffset: Int,
colorAttribute: ByteArray,
maskChunkOffset: Int,
maskAttribute: ByteArray?,
anchorX: Int,
anchorY: Int,
): ClipDecodedRaster? {
val grid = parseAttributeGrid(colorAttribute) ?: return null
if (grid.columns <= 0 || grid.rows <= 0) {
return null
}
val tiles = walkBlockData(fileBytes, colorChunkOffset)
val nonEmpty = tiles.filter { tile -> tile.bytes.isNotEmpty() }
if (nonEmpty.isEmpty()) {
return null
}
// Mask tiles keyed by (col, row), aligned to color tiles (shared canvas-0,0 anchor). Absent
// for layers without a mask, and per-tile-absent where the mask InitColor (255) applies.
val maskTilesByColRow =
if (maskAttribute != null && maskChunkOffset >= 0) {
buildMaskTiles(fileBytes, maskChunkOffset, maskAttribute)
} else {
emptyMap()
}
// Crop to the bounding box of non-empty tiles - bounds memory for large, mostly-empty layers
// and matches the KRA reader's union-of-tiles cropping.
var minColumn = Int.MAX_VALUE
var minRow = Int.MAX_VALUE
var maxColumn = Int.MIN_VALUE
var maxRow = Int.MIN_VALUE
for (tile in nonEmpty) {
val column = tile.index % grid.columns
val row = tile.index / grid.columns
if (column < minColumn) {
minColumn = column
}
if (row < minRow) {
minRow = row
}
if (column > maxColumn) {
maxColumn = column
}
if (row > maxRow) {
maxRow = row
}
}
val widthPx = (maxColumn - minColumn + 1) * TILE
val heightPx = (maxRow - minRow + 1) * TILE
val rgba = ByteArray(widthPx * heightPx * 4)
val inflateBuffer = ByteArray(MAX_TILE_BYTES)
for (tile in nonEmpty) {
val inflatedLength = inflateTile(tile.bytes, inflateBuffer)
// Identify the color mode from the tile size; skip an unrecognized layout rather than guess.
val format = tileFormatFor(inflatedLength) ?: continue
val column = tile.index % grid.columns
val row = tile.index / grid.columns
val maskTile = maskTilesByColRow[packColumnRow(column, row)]
blitTile(
tileBytes = inflateBuffer,
format = format,
rgba = rgba,
destXTile = (column - minColumn) * TILE,
destYTile = (row - minRow) * TILE,
rowStridePx = widthPx,
maskTile = maskTile,
)
}
val bounds =
LayerBounds(
left = anchorX + minColumn * TILE,
top = anchorY + minRow * TILE,
width = widthPx,
height = heightPx,
)
return ClipDecodedRaster(bounds, LayerRaster(width = widthPx, height = heightPx, rgba = rgba))
}
/**
* Decodes a layer's mask offscreen into its non-empty grayscale tiles, keyed by `(col, row)`.
*
* Each mask tile inflates to a single-channel 256x256 plane (TILE_PIXELS bytes). Empty tiles are
* omitted: their absence signals the mask InitColor (255, fully visible) at decode time.
*
* @param ByteArray fileBytes The complete .clip file.
* @param Int maskChunkOffset Absolute file offset of the mask CHNKExta chunk.
* @param ByteArray maskAttribute The mask Offscreen.Attribute (gives the mask grid columns).
* @return Map Non-empty mask tiles (65536-byte planes) keyed by packed (col, row).
*/
private fun buildMaskTiles(fileBytes: ByteArray, maskChunkOffset: Int, maskAttribute: ByteArray): Map<Long, ByteArray> {
val grid = parseAttributeGrid(maskAttribute) ?: return emptyMap()
if (grid.columns <= 0) {
return emptyMap()
}
val tiles = walkBlockData(fileBytes, maskChunkOffset)
val result = HashMap<Long, ByteArray>()
val buffer = ByteArray(MAX_TILE_BYTES)
for (tile in tiles) {
if (tile.bytes.isEmpty()) {
continue
}
val inflatedLength = inflateTile(tile.bytes, buffer)
// A mask follows the layer's color mode: 8-bit grayscale (TILE_PIXELS bytes) on RGBA/greyscale
// layers, or 1-bit (TILE_PIXELS/8 bytes, MSB-first) on monochrome layers. Normalize both to a
// per-pixel 0..255 plane so blitTile's alpha multiply is uniform. Skip any other size.
val maskPlane =
when (inflatedLength) {
TILE_PIXELS -> buffer.copyOf(TILE_PIXELS)
MONOCHROME_PLANE_BYTES -> expandBitPlaneToBytes(buffer)
else -> continue
}
val column = tile.index % grid.columns
val row = tile.index / grid.columns
result[packColumnRow(column, row)] = maskPlane
}
return result
}
/**
* Expands an MSB-first 1-bit plane (TILE_PIXELS/8 bytes) into a TILE_PIXELS-byte plane of 0/255,
* so a 1-bit mask multiplies alpha identically to an 8-bit mask (bit set => 255 reveals).
*
* @param ByteArray bits The inflated 1-bit plane (its first MONOCHROME_PLANE_BYTES bytes are used).
* @return ByteArray A TILE_PIXELS-byte plane, 255 where the bit is set and 0 otherwise.
*/
private fun expandBitPlaneToBytes(bits: ByteArray): ByteArray {
val plane = ByteArray(TILE_PIXELS)
for (pixelIndex in 0 until TILE_PIXELS) {
if (bitAt(bits, 0, pixelIndex)) {
plane[pixelIndex] = 0xFF.toByte()
}
}
return plane
}
/**
* Packs a tile (column, row) into a single Long map key.
*
* @param Int column The tile column.
* @param Int row The tile row.
* @return Long The packed key.
*/
private fun packColumnRow(column: Int, row: Int): Long = (column.toLong() shl 32) or (row.toLong() and 0xFFFFFFFFL)
/**
* Writes one inflated 256x256 tile into the assembled RGBA buffer at the given tile origin,
* expanding the tile's color mode to RGBA8888 and optionally baking in a grayscale mask tile.
*
* @param ByteArray tileBytes The inflated tile (alpha plane first, then the color plane).
* @param TileFormat format The tile's color mode (RGBA / greyscale / monochrome).
* @param ByteArray rgba The destination RGBA8888 buffer.
* @param Int destXTile Destination X of the tile's left edge, in pixels.
* @param Int destYTile Destination Y of the tile's top edge, in pixels.
* @param Int rowStridePx Destination buffer width in pixels.
* @param ByteArray? maskTile A 256x256 single-byte mask plane to bake into alpha, or null.
*/
private fun blitTile(
tileBytes: ByteArray,
format: TileFormat,
rgba: ByteArray,
destXTile: Int,
destYTile: Int,
rowStridePx: Int,
maskTile: ByteArray?,
) {
for (y in 0 until TILE) {
val sourceRow = y * TILE
var destination = ((destYTile + y) * rowStridePx + destXTile) * 4
for (x in 0 until TILE) {
val sourcePixel = sourceRow + x
val red: Int
val green: Int
val blue: Int
var alpha: Int
when (format) {
TileFormat.Rgba -> {
// CLIP: alpha plane [0, TILE_PIXELS), then interleaved B,G,R,(unused).
alpha = tileBytes[sourcePixel].toInt() and 0xFF
val colorBase = TILE_PIXELS + sourcePixel * 4
red = tileBytes[colorBase + 2].toInt() and 0xFF
green = tileBytes[colorBase + 1].toInt() and 0xFF
blue = tileBytes[colorBase].toInt() and 0xFF
}
TileFormat.Greyscale -> {
// CLIP: alpha plane [0, TILE_PIXELS), then an 8-bit gray plane.
alpha = tileBytes[sourcePixel].toInt() and 0xFF
val gray = tileBytes[TILE_PIXELS + sourcePixel].toInt() and 0xFF
red = gray
green = gray
blue = gray
}
TileFormat.Monochrome -> {
// CLIP: 1-bit alpha plane, then a 1-bit value plane (MSB-first); value 0 = black.
alpha = if (bitAt(tileBytes, 0, sourcePixel)) 0xFF else 0
val gray = if (bitAt(tileBytes, MONOCHROME_PLANE_BYTES, sourcePixel)) 0xFF else 0
red = gray
green = gray
blue = gray
}
}
if (maskTile != null) {
// Bake the mask: outputAlpha = layerAlpha * mask / 255 (mask byte is grayscale 0..255).
alpha = alpha * (maskTile[sourcePixel].toInt() and 0xFF) / 255
}
rgba[destination] = red.toByte()
rgba[destination + 1] = green.toByte()
rgba[destination + 2] = blue.toByte()
rgba[destination + 3] = alpha.toByte()
destination += 4
}
}
}
/**
* Reads one bit from an MSB-first 1-bit plane starting at [planeOffset].
*
* @param ByteArray bytes The tile buffer.
* @param Int planeOffset Byte offset of the 1-bit plane.
* @param Int pixelIndex Pixel index within the 256x256 tile.
* @return Boolean Whether the bit is set.
*/
private fun bitAt(bytes: ByteArray, planeOffset: Int, pixelIndex: Int): Boolean {
val byte = bytes[planeOffset + (pixelIndex shr 3)].toInt()
return (byte shr (7 - (pixelIndex and 7))) and 1 != 0
}
/**
* Inflates a tile body (`[4-byte LE length][zlib stream]`) into [destination], returning the
* number of decompressed bytes (0 on failure).
*
* @param ByteArray tileBytes The tile body including its 4-byte length prefix.
* @param ByteArray destination The reusable inflate buffer (sized to MAX_TILE_BYTES).
* @return Int The number of bytes inflated, or 0 if the stream was invalid.
*/
private fun inflateTile(tileBytes: ByteArray, destination: ByteArray): Int {
// The 4-byte little-endian prefix is the zlib stream length; inflating from offset 4 is enough.
val inflated = inflateZlib(tileBytes, 4, tileBytes.size - 4, destination.size)
inflated.copyInto(destination, 0, 0, minOf(inflated.size, destination.size))
return minOf(inflated.size, destination.size)
}
/** Columns/rows of a layer's tile grid, read from Offscreen.Attribute. */
private class AttributeGrid(val columns: Int, val rows: Int)
/**
* Parses the tile-grid dimensions out of Offscreen.Attribute.
*
* The Attribute is a serialized property block; the "Parameter" entry is followed by four
* big-endian u32s: padded width, padded height, column count, row count. Only the grid shape is
* needed to place tiles by their block index.
*
* @param ByteArray attribute The Offscreen.Attribute bytes.
* @return AttributeGrid The columns/rows, or null if the "Parameter" entry was not found.
*/
private fun parseAttributeGrid(attribute: ByteArray): AttributeGrid? {
// CLIP: Offscreen.Attribute - UTF-16BE "Parameter", then width, height, cols, rows (u32 BE).
val parameterTag = encodeUtf16Be("Parameter")
val tagAt = indexOf(attribute, parameterTag, 0)
if (tagAt < 0) {
return null
}
val fieldsAt = tagAt + parameterTag.size
if (fieldsAt + 16 > attribute.size) {
return null
}
val columns = readUInt32BE(attribute, fieldsAt + 8)
val rows = readUInt32BE(attribute, fieldsAt + 12)
return AttributeGrid(columns = columns, rows = rows)
}
/** One tile within a layer's external block data: its grid index and (possibly empty) body. */
private class BlockTile(val index: Int, val bytes: ByteArray)
/**
* Walks the external chunk's block data, returning each BlockDataBeginChunk's tile body (empty
* for tiles flagged as having no data).
*
* @param ByteArray fileBytes The complete .clip file.
* @param Int chunkOffset Absolute file offset of the CHNKExta chunk.
* @return List The tiles in encounter order.
*/
private fun walkBlockData(fileBytes: ByteArray, chunkOffset: Int): List<BlockTile> {
val chunkSize = readUInt64(fileBytes, chunkOffset + 8)
val blockStart = chunkOffset + CHUNK_HEADER_SIZE + EXTERNAL_HEADER_SIZE
val blockEnd = minOf(chunkOffset + CHUNK_HEADER_SIZE + chunkSize, fileBytes.size)
val tiles = ArrayList<BlockTile>()
var position = blockStart
while (position + 8 <= blockEnd) {
val first = readUInt32BE(fileBytes, position)
val second = readUInt32BELong(fileBytes, position + 4)
position += 8
val stringLength: Int
if (second == TAG_PREFIX) {
// No leading size word: the first u32 was the string length; rewind to the tag.
stringLength = first
position -= 4
} else {
stringLength = readUInt32BE(fileBytes, position - 4)
}
val tagBytes = stringLength * 2
if (position + tagBytes > blockEnd) {
break
}
val tag = fileBytes.copyOfRange(position, position + tagBytes)
position += tagBytes
when {
tag.contentEquals(BEGIN_TAG) -> {
if (position + 20 > blockEnd) {
break
}
val blockIndex = readUInt32BE(fileBytes, position)
val notEmpty = readUInt32BE(fileBytes, position + 16)
position += 20
if (notEmpty > 0) {
if (position + 4 > blockEnd) {
break
}
val tileLength = readUInt32BE(fileBytes, position)
position += 4
val tileEnd = minOf(position + tileLength, blockEnd)
tiles.add(BlockTile(blockIndex, fileBytes.copyOfRange(position, tileEnd)))
position = tileEnd
} else {
tiles.add(BlockTile(blockIndex, ByteArray(0)))
}
}
tag.contentEquals(END_TAG) -> Unit
tag.contentEquals(STATUS_TAG) -> position += 28
tag.contentEquals(CHECKSUM_TAG) -> {
position += 28
break
}
else -> break
}
}
return tiles
}
/**
* Returns the start index of needle within haystack at or after from, or -1.
*
* @param ByteArray haystack The buffer to search.
* @param ByteArray needle The byte sequence to find.
* @param Int from The first index to consider.
* @return Int The match start, or -1.
*/
private fun indexOf(haystack: ByteArray, needle: ByteArray, from: Int): Int {
if (needle.isEmpty() || haystack.size < needle.size) {
return -1
}
var start = maxOf(from, 0)
val lastStart = haystack.size - needle.size
while (start <= lastStart) {
var matchIndex = 0
while (matchIndex < needle.size && haystack[start + matchIndex] == needle[matchIndex]) {
matchIndex++
}
if (matchIndex == needle.size) {
return start
}
start++
}
return -1
}
/**
* Reads a big-endian unsigned 32-bit integer as an Int (CLIP block sizes fit comfortably).
*
* @param ByteArray bytes The buffer.
* @param Int at The offset of the most-significant byte.
* @return Int The decoded value.
*/
private fun readUInt32BE(bytes: ByteArray, at: Int): Int =
((bytes[at].toInt() and 0xFF) shl 24) or
((bytes[at + 1].toInt() and 0xFF) shl 16) or
((bytes[at + 2].toInt() and 0xFF) shl 8) or
(bytes[at + 3].toInt() and 0xFF)
/**
* Reads a big-endian unsigned 32-bit integer as a Long (for an unsigned tag-prefix compare).
*
* @param ByteArray bytes The buffer.
* @param Int at The offset of the most-significant byte.
* @return Long The decoded value in 0..0xFFFFFFFF.
*/
private fun readUInt32BELong(bytes: ByteArray, at: Int): Long = readUInt32BE(bytes, at).toLong() and 0xFFFFFFFFL
/**
* Reads a big-endian unsigned 64-bit integer as an Int (the whole file fits one ByteArray).
*
* @param ByteArray bytes The buffer.
* @param Int at The offset of the most-significant byte.
* @return Int The decoded value.
*/
private fun readUInt64(bytes: ByteArray, at: Int): Int {
var value = 0L
for (byteIndex in 0 until 8) {
value = (value shl 8) or (bytes[at + byteIndex].toLong() and 0xFF)
}
return value.toInt()
}
}
/** A decoded, placed layer raster: its canvas bounds and the cropped RGBA pixels. */
internal class ClipDecodedRaster(val bounds: LayerBounds, val raster: LayerRaster)
@@ -0,0 +1,193 @@
package org.umamo.format.clip
import org.umamo.format.FileKind
import org.umamo.format.art.ArtReader
import org.umamo.format.art.SourceArt
import org.umamo.format.clip.db.ClipDatabase
import org.umamo.format.clip.db.SelectAllLayers
import kotlin.math.roundToInt
/**
* Clip Studio Paint (.clip) reader (STRETCH, but the re-import-critical one).
*
* EN: `.clip` carries Celsys's rename/reorder-stable layer ids (Layer.MainId and Layer.LayerUuid),
* which give non-destructive re-import a reliable identity key PSD cannot. This reader parses the
* CSFCHUNK container down to the embedded SQLite database (CHNKSQLi) for the Canvas + Layer tables,
* and decodes the tiled raster from the CHNKExta chunks: ids, names, group hierarchy, order,
* opacity, blend, bounds, kind, visibility, RGBA/greyscale/monochrome pixels, masks (baked into
* alpha), and clipping. See docs/format/CLIP.md.
* JA: CLIP 読み込み。安定レイヤー ID が再取り込みの信頼性を生む。ラスタ(RGBA/グレースケール/モノクロ)も復号する。
*
* Cross-platform (JVM + Android): the only platform-specific step - opening a SQLite driver over the
* extracted database bytes - sits behind the [useClipDatabase] expect/actual seam (JVM JdbcSqliteDriver,
* Android AndroidSqliteDriver). The container parse and tile decode are pure jvmAndroidMain Kotlin.
* On Android, ClipAndroid.applicationContext must be set once at startup (the driver needs a Context).
*/
object ClipReader : ArtReader {
override val kind: FileKind = FileKind.Clip
/**
* True if [candidateBytes] starts with the CSFCHUNK container magic.
*
* @param ByteArray candidateBytes Candidate file contents.
* @return Boolean Whether the leading bytes are the CLIP magic.
*/
override fun matches(candidateBytes: ByteArray): Boolean = ClipContainer.isClip(candidateBytes)
/**
* Parses a complete .clip file into the neutral SourceArt model (layer tree only, this pass).
*
* @param ByteArray bytes The complete .clip file contents.
* @return SourceArt The canvas size and the ordered, bottom-to-top layer list.
*/
override fun read(bytes: ByteArray): SourceArt {
// CLIP: CSFCHUNK container -> CHNKSQLi payload holds the layer table; raster tiles live in the
// CHNKExta chunks of the same byte stream, located via ExternalChunk offsets.
val databaseBytes = ClipContainer.extractSqliteDatabase(bytes)
return readDatabase(bytes, databaseBytes)
}
/**
* Reads the Canvas + Layer tables, decodes each layer's raster from [fileBytes], and assembles
* SourceArt. The driver lifecycle (write a temp DB, open the platform driver, close, clean up)
* lives in [useClipDatabase]; everything here is platform-neutral. The embedded database already
* has its tables, so the generated SELECTs run WITHOUT Schema.create.
*
* @param ByteArray fileBytes The complete .clip file (raster tiles are read from it).
* @param ByteArray databaseBytes The raw "SQLite format 3" bytes from the CHNKSQLi chunk.
* @return SourceArt The parsed document.
*/
private fun readDatabase(fileBytes: ByteArray, databaseBytes: ByteArray): SourceArt =
useClipDatabase(databaseBytes) { database ->
val canvasRow =
database.clipQueries.selectCanvas().executeAsOneOrNull()
?: throw IllegalArgumentException("CLIP database has no Canvas row")
val canvas =
ClipCanvas(
// CLIP: Canvas dimensions are REAL pixels; round to the integer pixel grid.
widthPx = (canvasRow.CanvasWidth ?: 0.0).roundToInt(),
heightPx = (canvasRow.CanvasHeight ?: 0.0).roundToInt(),
rootFolderId = canvasRow.CanvasRootFolder ?: 0L,
)
val rows = database.clipQueries.selectAllLayers().executeAsList().map { row -> row.toClipLayerRow() }
val rastersByMainId = decodeRasters(fileBytes, database, rows)
val textLayerIds = readTextLayerIds(database)
val tree = buildSourceTree(canvas, rows, rastersByMainId, textLayerIds)
ClipSourceArt(
widthPx = canvas.widthPx,
heightPx = canvas.heightPx,
layers = tree.layers,
groups = tree.groups,
)
}
/**
* Decodes every layer's base-resolution raster, keyed by layer MainId.
*
* Resolves each layer's external-chunk reference (Offscreen.BlockData) to a file offset via the
* ExternalChunk table, then hands the Attribute tile-index and chunk offset to [ClipRaster].
* Layers with no decodable content are simply omitted (the tree builder falls back to a
* placeholder for them).
*
* @param ByteArray fileBytes The complete .clip file.
* @param ClipDatabase database The open CLIP database.
* @param List rows The layer rows (for per-layer canvas offsets).
* @return Map Decoded rasters keyed by layer MainId.
*/
private fun decodeRasters(
fileBytes: ByteArray,
database: ClipDatabase,
rows: List<ClipLayerRow>,
): Map<Long, ClipDecodedRaster> {
// CLIP: ExternalChunk.ExternalID ("extrnlid"+GUID) -> absolute CHNKExta file offset.
val offsetByExternalId = HashMap<String, Int>()
for (external in database.clipQueries.selectExternalChunks().executeAsList()) {
val externalId = external.ExternalID ?: continue
val offset = external.Offset ?: continue
offsetByExternalId[externalId.decodeToString()] = offset.toInt()
}
val layerOffsetsByMainId = rows.associateBy { row -> row.mainId }
// Per-layer mask offscreen (Attribute + external chunk offset), keyed by layer MainId.
val maskByMainId = HashMap<Long, MaskSource>()
for (maskRow in database.clipQueries.selectLayerMaskRasters().executeAsList()) {
val mainId = maskRow.MainId ?: continue
val attribute = maskRow.Attribute ?: continue
// BlockData is non-null by construction: selectLayerMaskRasters filters `O.BlockData IS NOT NULL`,
// so SQLDelight types it non-nullable (unlike MainId/Attribute, which carry no such predicate).
val blockData = maskRow.BlockData
val chunkOffset = offsetByExternalId[blockData.decodeToString()] ?: continue
maskByMainId[mainId] = MaskSource(chunkOffset = chunkOffset, attribute = attribute)
}
val rasters = HashMap<Long, ClipDecodedRaster>()
for (rasterRow in database.clipQueries.selectLayerRasters().executeAsList()) {
val mainId = rasterRow.MainId ?: continue
val attribute = rasterRow.Attribute ?: continue
// BlockData is non-null by construction: selectLayerRasters filters `O.BlockData IS NOT NULL`,
// so SQLDelight types it non-nullable (unlike MainId/Attribute, which carry no such predicate).
val blockData = rasterRow.BlockData
val chunkOffset = offsetByExternalId[blockData.decodeToString()] ?: continue
val layerRow = layerOffsetsByMainId[mainId] ?: continue
val mask = maskByMainId[mainId]
val decoded =
ClipRaster.decodeLayer(
fileBytes = fileBytes,
colorChunkOffset = chunkOffset,
colorAttribute = attribute,
maskChunkOffset = mask?.chunkOffset ?: -1,
maskAttribute = mask?.attribute,
// CLIP: tile-grid anchor = LayerOffset + LayerRenderOffscrOffset (canvas-aligned).
anchorX = (layerRow.offsetX + layerRow.renderOffscrX).toInt(),
anchorY = (layerRow.offsetY + layerRow.renderOffscrY).toInt(),
)
if (decoded != null) {
rasters[mainId] = decoded
}
}
return rasters
}
}
/**
* Reads the set of text-layer MainIds, tolerating older CLIP schemas that lack the TextLayerType
* column. The CLIP SQLite schema gains columns across Clip Studio versions, so this version-specific
* lookup is isolated and its failure is swallowed - an absent column simply means "no text layers
* identified" (they fall back to Vector).
*
* @param ClipDatabase database The open CLIP database.
* @return Set The text-layer MainIds, or empty if the column is absent.
*/
private fun readTextLayerIds(database: ClipDatabase): Set<Long> =
runCatching {
database.clipQueries.selectTextLayerIds().executeAsList().mapNotNull { row -> row.MainId }.toSet()
}.getOrDefault(emptySet())
/** A layer's mask offscreen: the external chunk offset and the mask Attribute tile index. */
private class MaskSource(val chunkOffset: Int, val attribute: ByteArray)
/**
* Maps a SQLDelight-generated Layer row to the internal [ClipLayerRow], defaulting NULL columns.
*
* @return ClipLayerRow The reduced, null-defaulted row.
*/
private fun SelectAllLayers.toClipLayerRow(): ClipLayerRow =
ClipLayerRow(
mainId = MainId ?: 0L,
name = LayerName ?: "",
folder = LayerFolder ?: 0L,
type = LayerType ?: 0L,
visibility = LayerVisibility ?: 1L,
opacity = LayerOpacity ?: 256L, // CLIP: absent opacity defaults to fully opaque (256).
composite = LayerComposite ?: 0L,
clip = LayerClip ?: 0L,
offsetX = LayerOffsetX ?: 0L,
offsetY = LayerOffsetY ?: 0L,
firstChildIndex = LayerFirstChildIndex ?: 0L,
nextIndex = LayerNextIndex ?: 0L,
uuid = LayerUuid,
renderOffscrX = LayerRenderOffscrOffsetX ?: 0L,
renderOffscrY = LayerRenderOffscrOffsetY ?: 0L,
)
@@ -0,0 +1,69 @@
package org.umamo.format.cmo3
/**
* The Cubism SDK version ladder that `CModelSource.targetVersionNo` denotes - the "Model target
* version selection" the official editor stores per document.
*
* The on-disk value is an era-specific LITERAL per version, not one formula: the editor keeps
* the encoding scheme that was current when each SDK shipped (3.x = major*1000 + minor*10,
* 4.0 = major*100000, 4.2+ = major*1_000_000 + minor*10_000). A single formula is wrong by
* observation - it would predict 3030000 for 3.3 where the editor writes 3030.
* Corpus evidence:
*
* Cubism 3.0 -> 3000 (modelD - older editors)
* Cubism 3.3 -> 3030 (ModelWith[out]OffscreenSDK3.3)
* Cubism 4.0 -> 400000 (EricaTamamo, ModelWithoutOffscreenSDK4.0)
* Cubism 4.2 -> 4020000 (ModelWithoutOffscreenSDK4.2)
* Cubism 5.0 -> 5000000 (modelB, modelC)
* Cubism 5.3 -> 5030000 (modelA, ModelWithOffscreen family)
* SDK(N/A) -> 9000000 (ModelWithoutOffscreenSDKNA) - see [LATEST_VERSION_NO]
*
* This type is pure CMO3 format knowledge: it knows nothing about editor gating policy or any
* runtime target - that mapping lives above `:format`.
*/
enum class Cmo3TargetVersion(val major: Int, val minor: Int, val versionNo: Int) {
// CMO3: CModelSource field targetVersionNo - one entry per observed literal (table above).
V30(3, 0, 3_000),
V33(3, 3, 3_030),
V40(4, 0, 400_000),
V42(4, 2, 4_020_000),
V50(5, 0, 5_000_000),
V53(5, 3, 5_030_000),
;
/**
* The value this version would take under the modern 4.2+ scheme, accepted as a tolerant-read
* alias because a future editor revision normalizing old projects would most plausibly emit it.
*/
private val modernVersionNo: Int
get() = major * 1_000_000 + minor * 10_000
companion object {
/**
* The value the editor writes for the "SDK(N/A)/Latest Cubism" selection - no version
* ceiling at all. CMO3: CModelSource field targetVersionNo. Deliberately not an enum
* entry: it names the ABSENCE of a target version, so [fromVersionNo] returns null for it
* and callers persist it through this constant.
*/
const val LATEST_VERSION_NO: Int = 9_000_000
/**
* Decodes a raw `targetVersionNo` into a known Cubism SDK target version.
*
* Matches the observed per-era literals first, then the modern-scheme equivalents as a
* tolerant-read fallback. Everything else is null: the field being absent, unknown values,
* and [LATEST_VERSION_NO] (a target-less document has no target version).
*
* @param Int? versionNo The raw field value, or null when the document carries none.
* @return Cmo3TargetVersion? The matching version, or null for no/unknown version.
*/
fun fromVersionNo(versionNo: Int?): Cmo3TargetVersion? {
// CMO3: CModelSource field targetVersionNo.
if (versionNo == null) {
return null
}
return entries.firstOrNull { it.versionNo == versionNo }
?: entries.firstOrNull { it.modernVersionNo == versionNo }
}
}
}
@@ -0,0 +1,60 @@
package org.umamo.format.cmo3
import org.umamo.format.FormatVersion
/**
* Known CMO3 schema generations Umamo supports.
*
* Modelled as a `sealed interface` so the compiler forces every `when` over versions to be
* exhaustive: adding a generation without handling it everywhere becomes a compile error, not a
* silent runtime gap.
*
* 対応する CMO3 スキーマ世代。sealed interface により `when` の網羅性をコンパイラが強制する。
*/
sealed interface Cmo3Version : FormatVersion {
// `data object` = a singleton with generated equals/hashCode/toString. There is exactly one
// of each version, so an object (not a class) is the right modelling.
data object V3 : Cmo3Version {
override val label = "cmo3 / Cubism 3.x"
}
data object V4 : Cmo3Version {
override val label = "cmo3 / Cubism 4.x"
}
data object V5 : Cmo3Version {
override val label = "cmo3 / Cubism 5.x"
}
/**
* Human-readable summary. The `when` has no `else` branch on purpose - the sealed hierarchy makes
* it exhaustive, so a future `V6` won't compile until handled here.
*
* @return String The summary sentence.
*/
override fun describe(): String =
when (this) {
V3 -> "Supported: $label"
V4 -> "Supported: $label"
V5 -> "Supported: $label"
}
companion object {
/**
* Maps a `<root fileFormatVersion="...">` attribute value to a known generation, or null.
*
* The attribute is a packed decimal whose leading digit is the Cubism major generation
* (corpus: 401010001 and 400050002 are 4.x, 501030000 is 5.x) - CMO3.md §3 Document shape.
*
* @param String raw The attribute text.
* @return Cmo3Version? The matching generation, or null for garbage or an unknown generation.
*/
fun fromFileFormatVersion(raw: String): Cmo3Version? =
when (raw.trim().toLongOrNull()?.div(100_000_000L)) {
3L -> V3
4L -> V4
5L -> V5
else -> null
}
}
}
@@ -0,0 +1,85 @@
package org.umamo.format.cmo3.caff
/**
* One logical file inside a CAFF archive. [content] is the fully-decoded payload
* (de-obfuscated and decompressed); compression/obfuscation describe how it is stored on disk.
*
* EN: Holds decoded bytes rather than a file offset.
* JA: オフセットではなくデコード済みバイトを保持する。
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §1 FILE TABLE</a>
*/
public class CaffEntry(
public val path: String,
public val tag: String,
public val content: ByteArray,
public val compression: CompressOption = CompressOption.RAW,
public val obfuscated: Boolean = true,
)
/**
* The CAFF preview thumbnail. Most cmo3 files carry [present] == false (NO_PREVIEW).
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §1 PREVIEW</a>
*/
public class CaffPreview(
public val imageType: ImageType,
public val colorType: ColorType,
public val width: Int,
public val height: Int,
/** The preview PNG bytes, or null when [imageType] is NO_PREVIEW. */
public val png: ByteArray?,
) {
public val present: Boolean get() = imageType == ImageType.PNG && png != null
public companion object {
/** A NO_PREVIEW placeholder (what real cmo3 files contain). */
public fun none(): CaffPreview =
CaffPreview(ImageType.NO_PREVIEW, ColorType.NO_PREVIEW, 0, 0, null)
}
}
/**
* An in-memory CAFF archive: header metadata, optional preview, and the ordered file entries.
*
* EN: Entry order is significant - the model serializer assigns file paths positionally, and
* consumers map them by order (e.g. the i-th CImageResource ↔ the i-th imageFileBuf*).
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §1 Container: CAFF</a>
*/
public class CaffArchive(
/** 4-char format identifier; "----" for cmo3. */
public val formatIdentifier: String = DEFAULT_FORMAT_IDENTIFIER,
/** 3-element format version; {0,0,0} for the sample. */
public val formatVersion: IntArray = intArrayOf(0, 0, 0),
/** 3-element archive version; {0,0,0} for the sample. */
public val archiveVersion: IntArray = intArrayOf(0, 0, 0),
/** XOR key; 0 => not obfuscated. */
public val obfuscateKey: Int = 0,
public val preview: CaffPreview = CaffPreview.none(),
public val entries: List<CaffEntry> = emptyList(),
) {
/** Returns the first entry carrying [tag], or null. */
public fun firstByTag(tag: String): CaffEntry? = entries.firstOrNull { it.tag == tag }
/** Returns all entries carrying [tag], in archive order. */
public fun allByTag(tag: String): List<CaffEntry> = entries.filter { it.tag == tag }
/** Returns the first entry with an exact [path], or null. */
public fun byPath(path: String): CaffEntry? = entries.firstOrNull { it.path == path }
/** Returns a copy of this archive with a different entry list (other metadata unchanged). */
public fun withEntries(entries: List<CaffEntry>): CaffArchive =
CaffArchive(formatIdentifier, formatVersion, archiveVersion, obfuscateKey, preview, entries)
public companion object {
public const val MAGIC: String = "CAFF"
public const val DEFAULT_FORMAT_IDENTIFIER: String = "----"
/** Archive tag for the serialized model document (main.xml). */
public const val TAG_MAIN_XML: String = "main_xml"
/** Archive tag for the preview image entry. */
public const val TAG_PREVIEW: String = "preview"
}
}
@@ -0,0 +1,294 @@
package org.umamo.format.cmo3.caff
import org.umamo.format.cmo3.io.BinaryReader
import org.umamo.format.cmo3.io.BinaryWriter
/**
* Reads and writes the CAFF container. Stateless; operates on whole byte arrays.
*
* EN: Layout is header (unobfuscated) -> preview block (unobfuscated) -> file table (obfuscated)
* -> concatenated blobs -> guard bytes 'b''c'. See CMO3.md §1 for the exact byte map.
* JA: ヘッダ → プレビュー → ファイルテーブル → ブロブ群 → ガードバイト。詳細は CMO3.md §1。
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §1 Container: CAFF</a>
*/
public object CaffCodec {
private const val HEADER_AND_PREVIEW_BYTES = 54 // header(26) + preview(28); blobs/table follow
private const val GUARD_BYTE_0 = 0x62 // 'b'
private const val GUARD_BYTE_1 = 0x63 // 'c'
private class EntryMeta(
val path: String,
val tag: String,
val offset: Int,
val storedSize: Int,
val obfuscated: Boolean,
val compression: CompressOption,
)
private class HeaderAndTable(
val archiveVersion: IntArray,
val formatIdentifier: String,
val formatVersion: IntArray,
val obfuscateKey: Int,
val previewImageType: ImageType,
val previewColorType: ColorType,
val previewWidth: Int,
val previewHeight: Int,
val previewStartPos: Long,
val previewFileSize: Int,
val metas: List<EntryMeta>,
)
/**
* True if [candidateBytes] starts with the unobfuscated `CAFF` magic.
*
* The magic sits at +0x00 and is read with XOR key 0 (cleartext), so a leading-bytes compare is
* a sound sniff without parsing the container - CMO3.md §1.
*
* @param ByteArray candidateBytes Candidate file contents.
* @return Boolean Whether this looks like a CAFF container (e.g. a `.cmo3`).
*/
public fun isCaff(candidateBytes: ByteArray): Boolean {
val magic = CaffArchive.MAGIC.encodeToByteArray() // CAFF: magic @ +0x00, unobfuscated
if (candidateBytes.size < magic.size) {
return false
}
for (magicIndex in magic.indices) {
if (candidateBytes[magicIndex] != magic[magicIndex]) {
return false
}
}
return true
}
/**
* Parses the header, preview block, and file table, leaving every blob undecoded.
*
* @param BinaryReader reader A reader positioned at the start of the file.
* @return HeaderAndTable The parsed container metadata and entry table.
*/
private fun readHeaderAndTable(reader: BinaryReader): HeaderAndTable {
// --- HEADER (not obfuscated) - CMO3.md §1 ---
val magic = reader.readBytes(4, 0).decodeToString()
require(magic == CaffArchive.MAGIC) { "not a CAFF file (magic=$magic)" }
val archiveVersion = IntArray(3) { reader.readU8(0) }
val formatIdentifier = reader.readBytes(4, 0).decodeToString()
val formatVersion = IntArray(3) { reader.readU8(0) }
val obfuscateKey = reader.readInt32(0)
reader.skip(8)
// --- PREVIEW (not obfuscated) - CMO3.md §1 ---
val previewImageType = ImageType.fromTypeNo(reader.readU8(0))
val previewColorType = ColorType.fromTypeNo(reader.readU8(0))
reader.skip(2)
val previewWidth = reader.readInt16(0).toInt()
val previewHeight = reader.readInt16(0).toInt()
val previewStartPos = reader.readInt64(0) and 0xFFFFFFFFL
val previewFileSize = reader.readInt32(0)
reader.skip(8)
// --- FILE TABLE (obfuscated with obfuscateKey) - CMO3.md §1 ---
val count = reader.readInt32(obfuscateKey)
val metas = ArrayList<EntryMeta>(count)
for (entryIndex in 0 until count) {
val path = reader.readString(obfuscateKey)
val tag = reader.readString(obfuscateKey)
// CMO3: startPos high word is a writer artifact; the real offset is the low 32 bits.
val startPos = reader.readInt64(obfuscateKey) and 0xFFFFFFFFL
val fileSize = reader.readInt32(obfuscateKey)
val obfuscated = reader.readBool(obfuscateKey)
val compression = CompressOption.fromSerializeNo(reader.readU8(obfuscateKey))
reader.skip(8)
metas.add(EntryMeta(path, tag, startPos.toInt(), fileSize, obfuscated, compression))
}
return HeaderAndTable(
archiveVersion,
formatIdentifier,
formatVersion,
obfuscateKey,
previewImageType,
previewColorType,
previewWidth,
previewHeight,
previewStartPos,
previewFileSize,
metas,
)
}
/**
* Slices, de-obfuscates, and decompresses one entry's blob.
*
* @param BinaryReader reader The reader over the full file bytes.
* @param EntryMeta meta The entry's file-table record.
* @param Int obfuscateKey The archive's XOR key.
* @return CaffEntry The decoded entry.
*/
private fun decodeEntry(reader: BinaryReader, meta: EntryMeta, obfuscateKey: Int): CaffEntry {
reader.seek(meta.offset)
val stored = reader.readBytes(meta.storedSize, if (meta.obfuscated) obfuscateKey else 0)
val content = if (meta.compression.isCompressed) CaffZip.unzipSingle(stored) else stored
return CaffEntry(meta.path, meta.tag, content, meta.compression, meta.obfuscated)
}
/**
* Parses a CAFF archive from its raw bytes, decoding every entry's payload.
*
* @param ByteArray bytes The full .cmo3 (or other CAFF) file contents.
* @return CaffArchive The decoded archive.
*/
public fun read(bytes: ByteArray): CaffArchive {
val reader = BinaryReader(bytes)
val parsed = readHeaderAndTable(reader)
// --- BLOBS: slice, de-obfuscate, decompress ---
val entries = parsed.metas.map { meta -> decodeEntry(reader, meta, parsed.obfuscateKey) }
// Preview blob (RAW, not obfuscated)
val preview =
if (parsed.previewImageType == ImageType.PNG && parsed.previewFileSize > 0) {
reader.seek(parsed.previewStartPos.toInt())
val png = reader.readBytes(parsed.previewFileSize, 0)
CaffPreview(parsed.previewImageType, parsed.previewColorType, parsed.previewWidth, parsed.previewHeight, png)
} else {
CaffPreview(parsed.previewImageType, parsed.previewColorType, parsed.previewWidth, parsed.previewHeight, null)
}
return CaffArchive(
parsed.formatIdentifier,
parsed.formatVersion,
parsed.archiveVersion,
parsed.obfuscateKey,
preview,
entries,
)
}
/**
* Decodes only the first entry carrying [tag], leaving every other blob untouched.
*
* A cheap probe next to [read]: the header and file table are parsed (CMO3.md §1 FILE TABLE), but
* just the matching blob is de-obfuscated and decompressed - a version sniff over a `.cmo3` skips
* inflating the embedded layer PNGs this way.
*
* @param ByteArray bytes The full .cmo3 (or other CAFF) file contents.
* @param String tag The archive tag to look up (e.g. [CaffArchive.TAG_MAIN_XML]).
* @return CaffEntry? The decoded entry, or null when no entry carries the tag.
*/
public fun readFirstEntryByTag(bytes: ByteArray, tag: String): CaffEntry? {
val reader = BinaryReader(bytes)
val parsed = readHeaderAndTable(reader)
val meta = parsed.metas.firstOrNull { it.tag == tag } ?: return null
return decodeEntry(reader, meta, parsed.obfuscateKey)
}
/**
* Serializes an archive back into CAFF bytes. Offsets are computed in one pass (no seek-back
* fixup) and written as clean 64-bit values (high word 0).
*
* @param CaffArchive archive The archive to encode.
* @return ByteArray The complete CAFF file bytes.
*/
public fun write(archive: CaffArchive): ByteArray {
val key = archive.obfuscateKey
// Pre-encode each blob (compress, but XOR happens at write time via writeBytes).
val storedBlobs =
archive.entries.map { entry ->
if (entry.compression.isCompressed) {
CaffZip.zipSingle(entry.content, entry.compression.zipLevel)
} else {
entry.content
}
}
// Compute the table size so we know where blobs start, then assign sequential offsets.
var tableBytes = 4 // count
for (entry in archive.entries) {
tableBytes += varIntSize(entry.path.encodeToByteArray().size) + entry.path.encodeToByteArray().size
tableBytes += varIntSize(entry.tag.encodeToByteArray().size) + entry.tag.encodeToByteArray().size
tableBytes += 8 + 4 + 1 + 1 + 8 // startPos, fileSize, isObfuscated, compress, skip(8)
}
val blobStart = HEADER_AND_PREVIEW_BYTES + tableBytes
val offsets = IntArray(archive.entries.size)
var cursor = blobStart
for (index in storedBlobs.indices) {
offsets[index] = cursor
cursor += storedBlobs[index].size
}
val writer = BinaryWriter(cursor + 2)
// --- HEADER ---
writer.writeBytes(CaffArchive.MAGIC.encodeToByteArray(), 0)
for (versionPart in 0 until 3) writer.writeU8(archive.archiveVersion[versionPart], 0)
writer.writeBytes(padFour(archive.formatIdentifier), 0)
for (versionPart in 0 until 3) writer.writeU8(archive.formatVersion[versionPart], 0)
writer.writeInt32(key, 0)
writer.skip(8)
// --- PREVIEW ---
val previewEntryIndex = archive.entries.indexOfFirst { it.tag == CaffArchive.TAG_PREVIEW }
if (archive.preview.present && previewEntryIndex >= 0) {
writer.writeU8(ImageType.PNG.typeNo, 0)
writer.writeU8(archive.preview.colorType.typeNo, 0)
writer.skip(2)
writer.writeInt16(archive.preview.width, 0)
writer.writeInt16(archive.preview.height, 0)
writer.writeInt64(offsets[previewEntryIndex].toLong(), 0)
writer.writeInt32(storedBlobs[previewEntryIndex].size, 0)
writer.skip(8)
} else {
writer.writeU8(ImageType.NO_PREVIEW.typeNo, 0)
writer.writeU8(ColorType.NO_PREVIEW.typeNo, 0)
writer.skip(2)
writer.writeInt16(0, 0)
writer.writeInt16(0, 0)
writer.writeInt64(0, 0)
writer.writeInt32(0, 0)
writer.skip(8)
}
// --- FILE TABLE ---
writer.writeInt32(archive.entries.size, key)
for (index in archive.entries.indices) {
val entry = archive.entries[index]
writer.writeString(entry.path, key)
writer.writeString(entry.tag, key)
writer.writeInt64(offsets[index].toLong(), key)
writer.writeInt32(storedBlobs[index].size, key)
writer.writeBool(entry.obfuscated, key)
writer.writeU8(entry.compression.serializeNo, key)
writer.skip(8)
}
// --- BLOBS ---
for (index in archive.entries.indices) {
val entry = archive.entries[index]
writer.writeBytes(storedBlobs[index], if (entry.obfuscated) key else 0)
}
// --- GUARD BYTES (not obfuscated) ---
writer.writeU8(GUARD_BYTE_0, 0)
writer.writeU8(GUARD_BYTE_1, 0)
return writer.toByteArray()
}
private fun varIntSize(value: Int): Int =
when {
value < 0x80 -> 1
value < 0x4000 -> 2
value < 0x200000 -> 3
value < 0x10000000 -> 4
else -> throw IllegalArgumentException("varint too large: $value")
}
private fun padFour(identifier: String): ByteArray {
val bytes = identifier.encodeToByteArray()
require(bytes.size == 4) { "format identifier must be 4 bytes: '$identifier'" }
return bytes
}
}
@@ -0,0 +1,84 @@
package org.umamo.format.cmo3.caff
/**
* Preview image encoding, as stored in the CAFF header preview block.
*
* EN: typeNo is the on-disk byte value.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §1 PREVIEW</a>
*/
public enum class ImageType(public val typeNo: Int) {
NOT_INIT(0),
PNG(1),
NO_PREVIEW(127),
;
public companion object {
/**
* Resolves a preview ImageType from its on-disk byte.
*
* @param Int typeNo The stored byte value.
* @return ImageType The matching constant.
*/
public fun fromTypeNo(typeNo: Int): ImageType =
entries.firstOrNull { it.typeNo == typeNo }
?: throw IllegalArgumentException("unknown ImageType $typeNo")
}
}
/**
* Preview pixel layout, as stored in the CAFF header preview block.
*
* EN: Preview pixel layout.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §1 PREVIEW</a>
*/
public enum class ColorType(public val typeNo: Int) {
NOT_INIT(0),
ARGB(1),
RGB(2),
NO_PREVIEW(127),
;
public companion object {
/**
* Resolves a preview ColorType from its on-disk byte.
*
* @param Int typeNo The stored byte value.
* @return ColorType The matching constant.
*/
public fun fromTypeNo(typeNo: Int): ColorType =
entries.firstOrNull { it.typeNo == typeNo }
?: throw IllegalArgumentException("unknown ColorType $typeNo")
}
}
/**
* Per-entry storage mode. serializeNo is the on-disk byte; zipLevel is the java.util.zip level
* used when (re)compressing FAST/SMALL entries.
*
* EN: RAW = stored as-is (already-compressed PNGs);
* FAST/SMALL = a single-entry ("contents") Java Zip stream.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §1 Compression</a>
*/
public enum class CompressOption(public val serializeNo: Int, public val zipLevel: Int) {
RAW(16, 0),
FAST(33, 1),
SMALL(37, 5),
;
public val isCompressed: Boolean get() = this != RAW
public companion object {
/**
* Resolves a CompressOption from its on-disk serializeNo byte.
*
* @param Int serializeNo The stored byte value.
* @return CompressOption The matching constant.
*/
public fun fromSerializeNo(serializeNo: Int): CompressOption =
entries.firstOrNull { it.serializeNo == serializeNo }
?: throw IllegalArgumentException("unknown CompressOption $serializeNo")
}
}
@@ -0,0 +1,152 @@
package org.umamo.format.cmo3.caff
import kotlinx.datetime.TimeZone
import kotlinx.datetime.number
import kotlinx.datetime.toLocalDateTime
import okio.Buffer
import org.umamo.format.binary.ByteReader
import org.umamo.format.binary.Crc32
import org.umamo.format.binary.ZipRecords
import org.umamo.format.binary.deflateRawDeflate
import org.umamo.format.binary.inflateRawDeflate
import kotlin.time.Clock
/**
* The single-entry zip framing CAFF wraps FAST/SMALL blobs in.
*
* A CAFF compressed blob is a PARTIAL zip stream holding one entry named "contents": a local file
* header, a raw DEFLATE payload, a data descriptor, and then the end of the blob. It carries no
* central directory and no EOCD — measured on the corpus, not assumed (CMO3.md §1 has the byte
* layout and the evidence). So this is not `ZipOutputStream` output and cannot be produced by it:
* that class always appends both records on close. The framing is pure byte manipulation instead.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §1 Compression</a>
*/
internal object CaffZip {
// CMO3: the compressed blob is a single-entry zip stream; the entry is always named "contents".
private val ENTRY_NAME = "contents".encodeToByteArray()
// ZIP: general-purpose flags. Bit 3 (0x08) says the CRC and sizes follow in a data descriptor
// rather than the local header; bit 11 (0x0800) declares the name UTF-8. The editor sets both
// (measured: 0x0808), so a real .cmo3 carries zeroed sizes up front — a reader that trusts them
// reads nothing.
private const val FLAGS = ZipRecords.FLAG_DATA_DESCRIPTOR or ZipRecords.FLAG_UTF8_NAME
/**
* Inflates a single-entry CAFF zip stream back to the raw payload.
*
* Reads only what the framing guarantees: the local header's name/extra lengths locate the
* payload, and the DEFLATE stream ends itself. The sizes in the local header are ignored because
* the editor zeroes them (flag bit 3); the real ones are in the trailing data descriptor, which is
* data the inflater simply stops before.
*
* @param ByteArray zipStream The full zip stream bytes (already de-obfuscated).
* @return ByteArray The decompressed "contents" payload.
*/
fun unzipSingle(zipStream: ByteArray): ByteArray {
require(zipStream.size >= ZipRecords.LOCAL_HEADER_SIZE) { "Empty CAFF zip stream" }
val reader = ByteReader(zipStream, littleEndian = true)
require(reader.u32(0) == ZipRecords.LOCAL_HEADER_SIGNATURE.toLong()) { "CAFF blob is not a zip local file header" }
// ZIP: local header @ +0x1A name length, @ +0x1C extra length; the payload follows both.
val nameLength = reader.u16(26)
val extraLength = reader.u16(28)
val payloadStart = ZipRecords.LOCAL_HEADER_SIZE + nameLength + extraLength
require(payloadStart <= zipStream.size) { "Truncated CAFF zip local header" }
return inflateRawDeflate(zipStream, payloadStart, zipStream.size - payloadStart, declaredSize(reader))
}
/**
* The uncompressed size the blob's trailing data descriptor declares, else [Int.MAX_VALUE].
*
* This is the only output bound the format offers. The CAFF file table's storedSize delimits the
* INPUT — compressed bytes — and says nothing about how far they inflate: the corpus blobs expand
* 3.5x to 6.7x, but DEFLATE reaches ~1000:1, so a crafted entry could otherwise balloon toward
* gigabytes in memory before anyone notices. A blob ends at its data descriptor (CMO3.md §1 has
* the measured layout and the per-sample numbers), and that record's usize field is exactly the
* bound wanted.
*
* Treated as a cap, never a promise: a descriptor that lies truncates only its own entry, and
* anything unrecognizable falls back to unbounded rather than corrupting an otherwise valid read.
*
* @param ByteReader reader The full blob, little-endian.
* @return Int The declared uncompressed size, or Int.MAX_VALUE when no usable descriptor is found.
*/
private fun declaredSize(reader: ByteReader): Int {
val blobSize = reader.bytes.size
if (blobSize < ZipRecords.LOCAL_HEADER_SIZE + ZipRecords.DATA_DESCRIPTOR_SIZE) {
return Int.MAX_VALUE
}
val descriptorStart = blobSize - ZipRecords.DATA_DESCRIPTOR_SIZE
if (reader.u32(descriptorStart) != ZipRecords.DATA_DESCRIPTOR_SIGNATURE.toLong()) {
return Int.MAX_VALUE
}
// ZIP: data descriptor @ +0x0C uncompressed size. Zero is what the LOCAL header carries, so a
// zero here reads as "not really a descriptor"; past Int range needs zip64 and cannot be a
// ByteArray length anyway. Both fall back rather than truncate.
val declared = reader.u32(descriptorStart + 12)
return if (declared in 1..Int.MAX_VALUE.toLong()) declared.toInt() else Int.MAX_VALUE
}
/**
* Wraps [contents] in a single-entry ("contents") zip stream at the given level.
*
* @param ByteArray contents The raw payload to compress.
* @param Int level DEFLATE level (CompressOption.zipLevel).
* @param Int dosDateTime The MS-DOS modification stamp: date in the high 16 bits, time in the
* low 16. Defaults to the local wall clock, which is what the editor
* writes; injectable so tests can assert on the emitted bytes.
* @return ByteArray The zip stream bytes (before any obfuscation).
*/
fun zipSingle(contents: ByteArray, level: Int, dosDateTime: Int = currentDosDateTime()): ByteArray {
val deflated = deflateRawDeflate(contents, level)
val checksum = Crc32().also { it.update(contents) }.value.toInt()
val out = Buffer()
// ZIP: local file header (APPNOTE.TXT 4.3.7).
// https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
out.writeIntLe(ZipRecords.LOCAL_HEADER_SIGNATURE)
// ZIP: version 2.0 — the minimum that understands DEFLATE, and what Java writes.
out.writeShortLe(ZipRecords.VERSION_DEFLATED)
out.writeShortLe(FLAGS)
out.writeShortLe(ZipRecords.METHOD_DEFLATED)
// ZIP: local header @ +0x0A time, @ +0x0C date. Both little-endian 16-bit, in LOCAL time.
out.writeShortLe(dosDateTime and 0xFFFF)
out.writeShortLe((dosDateTime ushr 16) and 0xFFFF)
// Zeroed here and carried in the data descriptor instead — that is what flag bit 3 means.
out.writeIntLe(0)
out.writeIntLe(0)
out.writeIntLe(0)
out.writeShortLe(ENTRY_NAME.size)
out.writeShortLe(0)
out.write(ENTRY_NAME)
out.write(deflated)
// ZIP: data descriptor (APPNOTE.TXT 4.3.9) — the real CRC and sizes.
out.writeIntLe(ZipRecords.DATA_DESCRIPTOR_SIGNATURE)
out.writeIntLe(checksum)
out.writeIntLe(deflated.size)
out.writeIntLe(contents.size)
// Ends here — no central directory, no end-of-central-directory record. That is not an
// omission, it is what a CAFF blob measurably is: de-obfuscating the corpus sample finds one
// PK\x03\x04 and one PK\x07\x08, and zero of either record (CMO3.md §1). Re-emitting without
// them reproduces the original's exact file size, which is the same fact from the other side.
// Writing them would append 76 bytes the format does not carry, growing the file on each save
// — and is why this cannot be ZipOutputStream, which emits both unconditionally on close.
return out.readByteArray()
}
/**
* The local wall clock now, as an MS-DOS date/time pair.
*
* Local, not UTC: a DOS timestamp has no zone, and the editor writes local time — matching it is
* the point of stamping a clock here at all.
*
* @return Int The stamp: date in the high 16 bits, time in the low 16.
*/
private fun currentDosDateTime(): Int {
val now = Clock.System.now().toLocalDateTime(TimeZone.currentSystemDefault())
return ZipRecords.dosDateTimeOf(now.year, now.month.number, now.day, now.hour, now.minute, now.second)
}
}
@@ -0,0 +1,163 @@
package org.umamo.format.cmo3.io
/**
* Big-endian, XOR-deobfuscating reader over a byte array.
*
* EN: All multi-byte integers
* are big-endian; an obfuscation key XORs values by width (byte=key&0xFF, short=key&0xFFFF,
* int=key, long=(key<<32)|key). A key of 0 means "not obfuscated".
* JA: 多バイト整数はビッグエンディアン。難読化キーで幅ごとに XOR する。
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §1 Container: CAFF</a>
*/
public class BinaryReader(private val data: ByteArray) {
/** Current read cursor, in bytes from the start of [data]. */
public var position: Int = 0
private set
/** Total length of the backing buffer. */
public val size: Int get() = data.size
/**
* Moves the cursor to an absolute byte offset.
*
* @param Int offset Absolute position to seek to.
*/
public fun seek(offset: Int) {
position = offset
}
/**
* Advances the cursor by [count] bytes without interpreting them.
*
* EN: CAFF "skip(n)" is a literal reserved gap, NOT alignment padding.
*
* @param Int count Number of bytes to skip.
*/
public fun skip(count: Int) {
position += count
}
/**
* Reads one unsigned byte (0..255), optionally XOR-deobfuscated.
*
* @param Int key Obfuscation key (0 = none).
* @return Int The byte value in 0..255.
*/
public fun readU8(key: Int): Int {
val raw = data[position].toInt() and 0xFF
position += 1
return raw xor (key and 0xFF)
}
/**
* Reads a big-endian signed 16-bit integer.
*
* @param Int key Obfuscation key (0 = none).
* @return Short The decoded value.
*/
public fun readInt16(key: Int): Short {
val high = data[position].toInt() and 0xFF
val low = data[position + 1].toInt() and 0xFF
position += 2
val combined = (high shl 8) or low
return (combined xor (key and 0xFFFF)).toShort()
}
/**
* Reads a big-endian signed 32-bit integer.
*
* @param Int key Obfuscation key (0 = none).
* @return Int The decoded value.
*/
public fun readInt32(key: Int): Int {
val byte0 = data[position].toInt() and 0xFF
val byte1 = data[position + 1].toInt() and 0xFF
val byte2 = data[position + 2].toInt() and 0xFF
val byte3 = data[position + 3].toInt() and 0xFF
position += 4
val combined = (byte0 shl 24) or (byte1 shl 16) or (byte2 shl 8) or byte3
return combined xor key
}
/**
* Reads a big-endian signed 64-bit integer.
*
* @param Int key Obfuscation key (0 = none).
* @return Long The decoded value.
*/
public fun readInt64(key: Int): Long {
var combined = 0L
for (byteIndex in 0 until 8) {
combined = (combined shl 8) or (data[position + byteIndex].toLong() and 0xFFL)
}
position += 8
// CMO3: the editor's 64-bit mask ORs the SIGN-EXTENDED key (see BinaryWriter.writeInt64);
// a negative key floods the high dword with ones.
val mask = (key.toLong() shl 32) or key.toLong()
return combined xor mask
}
/**
* Reads a boolean stored as a single byte (non-zero = true).
*
* @param Int key Obfuscation key (0 = none).
* @return Boolean The decoded flag.
*/
public fun readBool(key: Int): Boolean = readU8(key) != 0
/**
* Reads a 7-bit, MSB-first variable-length unsigned integer.
*
* EN: A 7-bit variable-length integer: each byte carries 7 value bits;
* the high bit signals continuation. Used as the length prefix for strings.
*
* @param Int key Obfuscation key (0 = none).
* @return Int The decoded length/count.
*/
public fun readVarInt(key: Int): Int {
val byte0 = readU8(key)
if (byte0 and 0x80 == 0) return byte0 and 0xFF
val byte1 = readU8(key)
if (byte1 and 0x80 == 0) return ((byte0 and 0x7F) shl 7) or (byte1 and 0x7F)
val byte2 = readU8(key)
if (byte2 and 0x80 == 0) {
return ((byte0 and 0x7F) shl 14) or ((byte1 and 0x7F) shl 7) or (byte2 and 0xFF)
}
val byte3 = readU8(key)
if (byte3 and 0x80 == 0) {
return ((byte0 and 0x7F) shl 21) or ((byte1 and 0x7F) shl 14) or
((byte2 and 0x7F) shl 7) or (byte3 and 0xFF)
}
throw IllegalStateException("varint exceeds 4 bytes at offset ${position - 4}")
}
/**
* Reads a UTF-8 string: a [readVarInt] byte length followed by that many XOR'd UTF-8 bytes.
*
* @param Int key Obfuscation key (0 = none).
* @return String The decoded string.
*/
public fun readString(key: Int): String {
val length = readVarInt(key)
val raw = readBytes(length, key)
return raw.decodeToString()
}
/**
* Reads [count] raw bytes, optionally XOR-deobfuscating each with key&0xFF.
*
* @param Int count Number of bytes to read.
* @param Int key Obfuscation key (0 = none).
* @return ByteArray A freshly allocated array of the (decoded) bytes.
*/
public fun readBytes(count: Int, key: Int): ByteArray {
val out = ByteArray(count)
val byteKey = (key and 0xFF).toByte()
for (index in 0 until count) {
out[index] = if (key == 0) data[position + index] else (data[position + index].toInt() xor byteKey.toInt()).toByte()
}
position += count
return out
}
}
@@ -0,0 +1,184 @@
package org.umamo.format.cmo3.io
/**
* Big-endian, XOR-obfuscating writer into a growable byte buffer.
*
* EN: Inverse of [BinaryReader];
* same big-endian + width-keyed XOR conventions.
* JA: [BinaryReader] の逆操作。
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §1 Container: CAFF</a>
*/
public class BinaryWriter(initialCapacity: Int = 64 * 1024) {
private var buffer = ByteArray(initialCapacity)
/** Number of bytes written so far (also the current write cursor). */
public var position: Int = 0
private set
private fun ensure(additional: Int) {
val needed = position + additional
if (needed > buffer.size) {
var newSize = buffer.size * 2
if (newSize < needed) newSize = needed
buffer = buffer.copyOf(newSize)
}
}
/** Returns a copy of the written bytes (length == [position]). */
public fun toByteArray(): ByteArray = buffer.copyOf(position)
/**
* Writes [count] zero bytes - a CAFF reserved "skip(n)" gap.
*
* @param Int count Number of zero bytes to emit.
*/
public fun skip(count: Int) {
ensure(count)
position += count
}
/**
* Overwrites an already-written big-endian int32 at an absolute offset (used for back-patching
* file offsets without a second streaming pass).
*
* @param Int offset Absolute byte offset of the 4-byte slot.
* @param Int value Value to store (already XOR-encoded by the caller if needed).
*/
public fun patchInt32(offset: Int, value: Int) {
buffer[offset] = (value ushr 24).toByte()
buffer[offset + 1] = (value ushr 16).toByte()
buffer[offset + 2] = (value ushr 8).toByte()
buffer[offset + 3] = value.toByte()
}
/**
* Writes one byte, XOR-obfuscated with key&0xFF.
*
* @param Int value Byte value (low 8 bits used).
* @param Int key Obfuscation key (0 = none).
*/
public fun writeU8(value: Int, key: Int) {
ensure(1)
buffer[position] = (value xor (key and 0xFF)).toByte()
position += 1
}
/**
* Writes a big-endian 16-bit integer, XOR-obfuscated with key&0xFFFF.
*
* @param Int value Value to write (low 16 bits used).
* @param Int key Obfuscation key (0 = none).
*/
public fun writeInt16(value: Int, key: Int) {
ensure(2)
val encoded = value xor (key and 0xFFFF)
buffer[position] = (encoded ushr 8).toByte()
buffer[position + 1] = encoded.toByte()
position += 2
}
/**
* Writes a big-endian 32-bit integer, XOR-obfuscated with the full key.
*
* @param Int value Value to write.
* @param Int key Obfuscation key (0 = none).
*/
public fun writeInt32(value: Int, key: Int) {
ensure(4)
val encoded = value xor key
buffer[position] = (encoded ushr 24).toByte()
buffer[position + 1] = (encoded ushr 16).toByte()
buffer[position + 2] = (encoded ushr 8).toByte()
buffer[position + 3] = encoded.toByte()
position += 4
}
/**
* Writes a big-endian 64-bit integer, XOR-obfuscated with ((long) key << 32) | key.
*
* CMO3: the editor's 64-bit mask ORs the SIGN-EXTENDED key, so a negative key floods the
* high dword to all-ones (corpus-pinned: every negative-key file stores 0xFFFFFFFF high
* dwords for sub-4GB offsets). A zero-extended mask matches only positive keys - the
* official reader then decodes garbage offsets and reports the file as empty.
*
* @param Long value Value to write.
* @param Int key Obfuscation key (0 = none).
*/
public fun writeInt64(value: Long, key: Int) {
ensure(8)
val mask = (key.toLong() shl 32) or key.toLong()
val encoded = value xor mask
for (byteIndex in 0 until 8) {
buffer[position + byteIndex] = (encoded ushr (56 - 8 * byteIndex)).toByte()
}
position += 8
}
/**
* Writes a boolean as a single XOR'd byte (1/0).
*
* @param Boolean value Flag to write.
* @param Int key Obfuscation key (0 = none).
*/
public fun writeBool(value: Boolean, key: Int): Unit = writeU8(if (value) 1 else 0, key)
/**
* Writes a 7-bit, MSB-first variable-length unsigned integer (inverse of [BinaryReader.readVarInt]).
*
* @param Int value Non-negative value to encode.
* @param Int key Obfuscation key (0 = none).
*/
public fun writeVarInt(value: Int, key: Int) {
when {
value < 0x80 -> writeU8(value, key)
value < 0x4000 -> {
writeU8((value shr 7) and 0x7F or 0x80, key)
writeU8(value and 0x7F, key)
}
value < 0x200000 -> {
writeU8((value shr 14) and 0x7F or 0x80, key)
writeU8((value shr 7) and 0x7F or 0x80, key)
writeU8(value and 0x7F, key)
}
value < 0x10000000 -> {
writeU8((value shr 21) and 0x7F or 0x80, key)
writeU8((value shr 14) and 0x7F or 0x80, key)
writeU8((value shr 7) and 0x7F or 0x80, key)
writeU8(value and 0x7F, key)
}
else -> throw IllegalArgumentException("varint too large: $value")
}
}
/**
* Writes a UTF-8 string: a [writeVarInt] length prefix followed by the XOR'd UTF-8 bytes.
*
* @param String value String to write.
* @param Int key Obfuscation key (0 = none).
*/
public fun writeString(value: String, key: Int) {
val utf8 = value.encodeToByteArray()
writeVarInt(utf8.size, key)
writeBytes(utf8, key)
}
/**
* Writes raw bytes, optionally XOR-obfuscating each with key&0xFF.
*
* @param ByteArray bytes Bytes to write.
* @param Int key Obfuscation key (0 = none).
*/
public fun writeBytes(bytes: ByteArray, key: Int) {
ensure(bytes.size)
if (key == 0) {
bytes.copyInto(buffer, position)
} else {
val byteKey = key and 0xFF
for (index in bytes.indices) {
buffer[position + index] = (bytes[index].toInt() xor byteKey).toByte()
}
}
position += bytes.size
}
}
@@ -0,0 +1,11 @@
# CMO3 model types mirror the Live2D on-disk schema VERBATIM. The reflection-based serializer
# derives each XML element/attribute name directly from the Kotlin class/property name, so
# identifiers like `imageFileBuf_size`, `CBlend_Normal`, `_modelImageGuid`, and `m00` are dictated
# by the format — renaming them to satisfy ktlint would break the CMO3 round-trip. This is the same
# "localize chrome/display, never format-level identifiers" rule from CLAUDE.md, applied to code.
# Scope is deliberately just this model/ subtree; the rest of the module stays strict.
# See docs/formats/CMO3.md §3 (Serializer mechanics).
[*.kt]
ktlint_standard_property-naming = disabled
ktlint_standard_backing-property-naming = disabled
ktlint_standard_class-naming = disabled
@@ -0,0 +1,265 @@
package org.umamo.format.cmo3.model.custom
import org.umamo.format.cmo3.model.type.FileRef
import org.umamo.format.cmo3.serialize.annotations.DontSerializeIfDefault
import org.umamo.format.cmo3.serialize.annotations.SerialAttribute
import org.umamo.format.cmo3.serialize.annotations.SerialName
import org.umamo.format.cmo3.serialize.annotations.SerialTag
/*
* Value/leaf classes whose scalar fields are written as attributes, modelled as reflective classes with
* @SerialAttribute for the fields the editor writes as attributes. Field order mirrors each class's
* serialize() method (verified by the byte-identity gate). Object fields are Any? - they reference
* already-typed or still-verbatim objects and round-trip by identity regardless.
*/
/** A float RGBA color: `red`/`green`/`blue`/`alpha` float attributes. */
@SerialTag("CFloatColor")
public class CFloatColor {
@SerialAttribute
public var red: Float = 0f
@SerialAttribute
public var green: Float = 0f
@SerialAttribute
public var blue: Float = 0f
@SerialAttribute
public var alpha: Float = 0f
}
/** A label color: `customizedColorInt` attribute + a `CLabelColorType` enum child. */
@SerialTag("CLabelColor")
public class CLabelColor {
@SerialAttribute
public var customizedColorInt: Int = 0
public var labelType: Any? = null
}
/*
* Deformer original-shape snapshots. I believe that that official Cubism Editor's Java subclasses shadow
* the same field names declared on ACDeformerOriginalShape, re-emitting them at this level too;
* they are modelled as distinct Kotlin properties carrying the on-disk name via @SerialName so that
* both levels round-trip independently.
*/
/** A warp-deformer original shape, extending the generated ACDeformerOriginalShape. */
@SerialTag("WarpDeformerOriginalShape")
public class WarpDeformerOriginalShape : org.umamo.format.cmo3.model.gen.ACDeformerOriginalShape() {
@SerialName("lastUpdatedTimeString")
public var ownLastUpdatedTimeString: String? = null
@SerialName("autoRefreshIsAvailable")
public var ownAutoRefreshIsAvailable: Boolean = false
@SerialName("creationMethod")
public var ownCreationMethod: Any? = null
@SerialName("col")
public var ownCol: Int = 0
@SerialName("row")
public var ownRow: Int = 0
}
/** A rotation-deformer original shape, extending the generated ACDeformerOriginalShape. */
@SerialTag("RotationDeformerOriginalShape")
public class RotationDeformerOriginalShape : org.umamo.format.cmo3.model.gen.ACDeformerOriginalShape() {
@SerialName("lastUpdatedTimeString")
public var ownLastUpdatedTimeString: String? = null
@SerialName("autoRefreshIsAvailable")
public var ownAutoRefreshIsAvailable: Boolean = false
@SerialName("creationMethod")
public var ownCreationMethod: Any? = null
@SerialName("col")
public var ownCol: Int = 0
@SerialName("row")
public var ownRow: Int = 0
}
/** A width/height size value: `width`, `height` attributes. */
@SerialTag("CSize")
public class CSize {
@SerialAttribute
public var width: Int = 0
@SerialAttribute
public var height: Int = 0
}
/**
* A rotation-deformer keyform: 4 float + 2 bool attributes,
* extending ACDeformerForm (the engine nests its `<super>` automatically).
*/
@SerialTag("CRotationDeformerForm")
public class CRotationDeformerForm : org.umamo.format.cmo3.model.gen.ACDeformerForm() {
@SerialAttribute
public var angle: Float = 0f
@SerialAttribute
public var originX: Float = 0f
@SerialAttribute
public var originY: Float = 0f
@SerialAttribute
public var scale: Float = 0f
@SerialAttribute
public var isReflectX: Boolean = false
@SerialAttribute
public var isReflectY: Boolean = false
}
/** A writable image: `width`/`height`/`type` attributes + an embedded image file. */
@SerialTag("CWritableImage")
public class CWritableImage {
@SerialAttribute
public var width: Int = 0
@SerialAttribute
public var height: Int = 0
@SerialAttribute
public var type: String = ""
public var image: FileRef? = null
}
/** A layer pixel resource: attributes + imageFileBuf/preview file children. */
@SerialTag("CImageResource")
public class CImageResource {
@SerialAttribute
public var width: Int = 0
@SerialAttribute
public var height: Int = 0
@SerialAttribute
public var type: String = ""
public var imageFileBuf: FileRef? = null
@SerialAttribute
public var imageFileBuf_size: Int = 0
@DontSerializeIfDefault
public var preview: FileRef? = null
@SerialAttribute
public var previewFileBuf_size: Int = 0
}
/** A filter instance: `filterName` attribute + object children. */
@SerialTag("FilterInstance")
public class FilterInstance {
@SerialAttribute
public var filterName: String = ""
public var filterDefGuid: Any? = null
public var filterDef: Any? = null
public var filterId: Any? = null
public var inputConnectors: Any? = null
public var outputConnectors: Any? = null
public var ownerFilterSet: Any? = null
}
/** A model image: `modelImageVersion` attribute + object children. */
@SerialTag("CModelImage")
public class CModelImage {
@SerialAttribute
public var modelImageVersion: Int = 0
public var guid: Any? = null
public var name: Any? = null
public var inputFilter: Any? = null
public var inputFilterEnv: Any? = null
public var _filteredImage: Any? = null
public var icon16: Any? = null
public var _materialLocalToCanvasTransform: Any? = null
public var _group: Any? = null
public var linkedRawImageGuids: Any? = null
public var cachedImageManager: Any? = null
public var memo: Any? = null
}
/** An editable mesh: `nextPointUid`/`useDelaunayTriangulation` attributes + object children. */
@SerialTag("GEditableMesh2")
public class GEditableMesh2 {
@SerialAttribute
public var nextPointUid: Int = 0
@SerialAttribute
public var useDelaunayTriangulation: Boolean = false
public var point: Any? = null
public var pointPriority: Any? = null
public var edge: Any? = null
public var edgePriority: Any? = null
public var pointUid: Any? = null
public var meshGuid: Any? = null
public var coordType: Any? = null
}
/**
* An image layer. Extends the generated ACImageLayer (whose
* ancestor ACLayerEntry carries the IOption `_optionOfIOption`); we override it here so the same value
* is written both in `<super>` and directly, matching the editor.
*/
@SerialTag("CLayer")
public class CLayer : org.umamo.format.cmo3.model.gen.ACImageLayer() {
public var imageResource: Any? = null
public var boundsOnImageDoc: Any? = null
public var layerIdentifier: Any? = null
public var icon16: Any? = null
public var icon64: Any? = null
public var layerInfo: Any? = null
override var _optionOfIOption: Any? = null
}
/** The model root: `isDefaultKeyformLocked` attribute + object children. */
@SerialTag("CModelSource")
public class CModelSource {
public var guid: Any? = null
public var name: Any? = null
public var editorEdition: Any? = null
public var canvas: Any? = null
public var parameterSourceSet: Any? = null
public var textureManager: Any? = null
public var useLegacyDrawOrder__testImpl: Any? = null
public var drawableSourceSet: Any? = null
public var deformerSourceSet: Any? = null
public var affecterSourceSet: Any? = null
public var partSourceSet: Any? = null
public var physicsSettingsSourceSet: Any? = null
public var rootPart: Any? = null
public var parameterGroupSet: Any? = null
public var rootParameterGroup: Any? = null
public var modelInfo: Any? = null
public var modelOptions: Any? = null
public var _icon64: Any? = null
public var _icon32: Any? = null
public var _icon16: Any? = null
public var gameMotionSet: Any? = null
@SerialAttribute
public var isDefaultKeyformLocked: Boolean = false
public var modelViewerSetting: Any? = null
public var guides: Any? = null
public var targetVersionNo: Any? = null
public var latestVersionOfLastModelerNo: Any? = null
public var artPathBrushesSetting: Any? = null
// Newer fields absent in older files: omit when null so pre-existing models round-trip.
@DontSerializeIfDefault
public var randomPoseSetting: Any? = null
@DontSerializeIfDefault
public var motionSyncSettingsSet: Any? = null
// CMO3: CModelSource field modelStateSetSet - the 5.4 tail (BareMinimum writes an empty
// CModelStateSetSet as the root's last child).
@DontSerializeIfDefault
public var modelStateSetSet: Any? = null
}
@@ -0,0 +1,67 @@
package org.umamo.format.cmo3.model.drawable
import org.umamo.format.cmo3.model.identity.Guid
import org.umamo.format.cmo3.model.type.GVector2
import org.umamo.format.cmo3.serialize.annotations.SerialTag
/**
* A named coordinate space. Fields derived from the serialized
* form: a single `coordName` string.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Serializer mechanics</a>
*/
@SerialTag("CoordType")
public class CoordType {
public var coordName: String = ""
}
/**
* A barycentric reference into an art-mesh triangle (3 point indices + weights).
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Serializer mechanics</a>
*/
@SerialTag("PointInTriangle")
public class PointInTriangle {
public var ptIndex1: Int = 0
public var weight1: Float = 0f
public var ptIndex2: Int = 0
public var weight2: Float = 0f
public var ptIndex3: Int = 0
public var weight3: Float = 0f
}
/**
* A point sampled along a controller curve. Mirrors the serialized form: a curve reference, the
* normalized/total parameter, distance, and a local position.
*
* EN: [curveId] references a CControllerCurveGuid (a [Guid]).
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Serializer mechanics</a>
*/
@SerialTag("PointOnCurve")
public class PointOnCurve {
public var curveId: Guid? = null
public var totalT: Float = 0f
public var distance: Float = 0f
public var _posOnLocal: GVector2? = null
}
/**
* A reference from a deformer/affecter to a point on an art-mesh keyform.
*
* EN: Object fields reference shared objects; not-yet-typed targets (keyForm CArtMeshForm,
* _artMeshSource CArtMeshSource) are held as Any? and round-trip as references regardless.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Serializer mechanics</a>
*/
@SerialTag("MeshPointRef")
public class MeshPointRef {
public var pointUid: Long = 0
public var coordType: CoordType? = null
public var keyForm: Any? = null
public var positions: FloatArray? = null
public var step: Int = 0
public var _artMeshSource: Any? = null
public var _index: Int = 0
public var artMeshGuid: Guid? = null
}
@@ -0,0 +1,30 @@
package org.umamo.format.cmo3.model.identity
/**
* A globally-unique entity reference (uuid) with a human-readable note:
* every entity (drawable, deformer, part, parameter, …) has a typed `*Guid`; on disk each is its own
* element tag carrying `uuid` + `note` attributes. [kind] holds that concrete tag.
*
* EN: One type covers all `*Guid` tags - they are opaque identity tokens with identical structure.
* JA: 全 `*Guid` を 1 型で表し、[kind] にタグ名を保持する。
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Serializer mechanics</a>
*/
public class Guid(public val kind: String) {
/** The UUID string, e.g. "e9fe6eff-953b-4ce2-be7c-4a7c3913686b". */
public var uuid: String = ""
/** The editor's debug note, e.g. "Root Parameter Group" or "(no debug info)". */
public var note: String = ""
}
/**
* A string-keyed entity id: each `*Id` is its own element tag with an
* `idstr` attribute. [kind] holds that concrete tag.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Serializer mechanics</a>
*/
public class Id(public val kind: String) {
/** The id string, e.g. "filter0" or "ilf_outputLayerData". */
public var idstr: String = ""
}
@@ -0,0 +1,17 @@
package org.umamo.format.cmo3.model.type
/**
* A `<file>` element, which the editor writes in two distinct shapes under the same tag:
* - `<file path="entry.png"/>` - an embedded CAFF entry; [archivePath] set.
* - `<file>C:\path\to.psd</file>` - a java.io.File path as text content (the File serializer);
* [textPath] set.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §1 Container / §3 Payload</a>
*/
public class FileRef {
/** Set when the file is an embedded archive entry (the `path` attribute). */
public var archivePath: String? = null
/** Set when the file is a plain filesystem path stored as element text. */
public var textPath: String? = null
}
@@ -0,0 +1,59 @@
package org.umamo.format.cmo3.model.type
import org.umamo.format.cmo3.serialize.annotations.DontSerialize
import org.umamo.format.cmo3.serialize.annotations.SerialTag
/**
* A 2D vector, serialized reflectively as `<f xs.n="x">`
* + `<f xs.n="y">` children.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Primitive & collection tags</a>
*/
@SerialTag("GVector2")
public class GVector2 {
public var x: Float = 0f
public var y: Float = 0f
}
/**
* An integer rectangle: reflective `<i>` children in x, y, width,
* height order.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Primitive & collection tags</a>
*/
@SerialTag("CRect")
public class CRect {
public var x: Int = 0
public var y: Int = 0
public var width: Int = 0
public var height: Int = 0
}
/**
* A color whose backing value is @DontSerialize (not persisted, matching the editor), so
* it serializes to an empty `<CColor/>` (the editor does not persist these UI colors). [argb] lets a
* caller hold a value, but it is never written, matching the editor.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Serializer mechanics</a>
*/
@SerialTag("CColor")
public class CColor {
@DontSerialize
public var argb: Int = 0
}
/**
* A 2x3 affine matrix, custom-serialized as the
* attributes m00, m01, m02, m10, m11, m12. Defaults to the identity transform.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Serializer mechanics</a>
*/
@SerialTag("CAffine")
public class CAffine {
public var m00: Float = 1f
public var m01: Float = 0f
public var m02: Float = 0f
public var m10: Float = 0f
public var m11: Float = 1f
public var m12: Float = 0f
}
@@ -0,0 +1,66 @@
package org.umamo.format.cmo3.serialize.annotations
/**
* Marks a property as serialized.
*
* EN: The editor serializes a property unless told otherwise; this annotation makes intent explicit
* and carries [readOnly] (deserialized but treated as read-only by the editor UI).
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Serializer mechanics</a>
*/
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.FIELD)
@Retention(AnnotationRetention.RUNTIME)
public annotation class Serialize(val readOnly: Boolean = false)
/** Excludes a property from serialization. */
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.FIELD)
@Retention(AnnotationRetention.RUNTIME)
public annotation class DontSerialize
/**
* Skips a property when its value equals the class's default-instance value.
*/
@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY, AnnotationTarget.FIELD)
@Retention(AnnotationRetention.RUNTIME)
public annotation class DontSerializeIfDefault
/**
* Suppresses serialization of the superclass as a nested `<super>` element.
*/
@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
public annotation class SuppressSerializeSuperClass
/**
* Pins the serialized element tag for a class (overrides the default simple-name mapping) and,
* optionally, the schema version emitted as a `<?version tag:version?>` PI.
*
* EN: The editor derives the tag from the class (simple name, or an `<?import?>`-qualified name).
* We make it explicit per class so the registry and version PIs are driven from the model.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Serializer mechanics</a>
*/
@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
public annotation class SerialTag(val tag: String, val version: Int = -1)
/**
* Serializes a property as an XML attribute on the owning element rather than a child element.
* For value classes whose scalar fields are written as attributes rather than child elements
* (e.g. CImageResource width/height, CModelSource isDefaultKeyformLocked).
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Serializer mechanics</a>
*/
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.FIELD)
@Retention(AnnotationRetention.RUNTIME)
public annotation class SerialAttribute(val name: String = "")
/**
* Overrides the serialized field name (xs.n) for a child-element property when it differs from the
* Kotlin property name - e.g. an on-disk name that is not a legal Kotlin identifier (`parameters.keys`).
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Serializer mechanics</a>
*/
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.FIELD)
@Retention(AnnotationRetention.RUNTIME)
public annotation class SerialName(val name: String)
@@ -0,0 +1,23 @@
package org.umamo.format.cmo3.type
/**
* A list type that serializes as `<carray_list>` (vs `<array_list>` for a plain ArrayList).
*
* The editor uses a distinct list type for most model collections, and the tag
* distinguishes it on disk, so model fields that are carray_list must use this type to round-trip.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Primitive & collection tags</a>
*/
public class CArrayList<E> private constructor(private val backing: MutableList<E>) : MutableList<E> by backing {
public constructor() : this(mutableListOf())
public constructor(initialCapacity: Int) : this(ArrayList(initialCapacity))
public constructor(elements: Collection<E>) : this(ArrayList(elements))
// Kotlin's `by` delegation forwards the interface, but NOT equals/hashCode/toString — they would
// silently fall back to identity, so two equal lists would compare unequal. Forward them by hand.
override fun equals(other: Any?): Boolean = backing == other
override fun hashCode(): Int = backing.hashCode()
override fun toString(): String = backing.toString()
}
@@ -0,0 +1,25 @@
package org.umamo.format.cmo3.type
/**
* A map that serializes as `<hash_map>` but preserves insertion/read order. The editor writes
* hash_map entries in JVM-hash order; reading into a plain HashMap and re-emitting would reorder
* them (Enum/object keys hash by identity), breaking byte-identity. Reading into this order-keeping
* type re-emits entries in their original document order.
*
* Delegates to a backing LinkedHashMap rather than extending it, for the same reason as [CArrayList]:
* `kotlin.collections.LinkedHashMap` is a typealias to the open java.util class on JVM but is FINAL
* on Kotlin/Native. The backing map is still a LinkedHashMap, so the insertion-order guarantee this
* type exists for is unchanged.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §3 Primitive & collection tags</a>
*/
public class CHashMap<K, V> private constructor(private val backing: MutableMap<K, V>) : MutableMap<K, V> by backing {
public constructor() : this(LinkedHashMap())
// As in CArrayList: `by` does not forward these, and identity equality would be a silent trap.
override fun equals(other: Any?): Boolean = backing == other
override fun hashCode(): Int = backing.hashCode()
override fun toString(): String = backing.toString()
}
@@ -0,0 +1,168 @@
// JPEG decoder, written from ITU-T T.81 (the JPEG specification). Section references in this package
// cite T.81; the fixed-point IDCT, upsampling filters, color-conversion constants, and progressive
// scan decoders follow the Independent JPEG Group's reference implementation (jidctint.c / jdsample.c
// / jdcolor.c / jdphuff.c) so output matches libjpeg exactly.
package org.umamo.format.jpeg
/**
* JPEG marker codes (T.81 Table B.1) and the zig-zag coefficient order (T.81 Figure A.6).
*/
internal object JpegConstants {
// Start Of Frame markers. SOF0/SOF1/SOF2 (sequential and progressive Huffman) are decodable; the
// rest are arithmetic-coded, differential, or lossless and are rejected.
const val MARKER_SOF0 = 0xC0 // Baseline DCT.
const val MARKER_SOF1 = 0xC1 // Extended sequential DCT, Huffman.
const val MARKER_SOF2 = 0xC2 // Progressive DCT, Huffman.
const val MARKER_SOF3 = 0xC3 // Lossless (sequential).
const val MARKER_SOF5 = 0xC5 // Differential sequential DCT.
const val MARKER_SOF6 = 0xC6 // Differential progressive DCT.
const val MARKER_SOF7 = 0xC7 // Differential lossless.
const val MARKER_SOF9 = 0xC9 // Extended sequential DCT, arithmetic.
const val MARKER_SOF10 = 0xCA // Progressive DCT, arithmetic.
const val MARKER_SOF11 = 0xCB // Lossless, arithmetic.
const val MARKER_SOF13 = 0xCD // Differential sequential DCT, arithmetic.
const val MARKER_SOF14 = 0xCE // Differential progressive DCT, arithmetic.
const val MARKER_SOF15 = 0xCF // Differential lossless, arithmetic.
const val MARKER_DHT = 0xC4 // Define Huffman Table.
const val MARKER_DAC = 0xCC // Define Arithmetic Coding conditioning.
const val MARKER_SOI = 0xD8 // Start Of Image.
const val MARKER_EOI = 0xD9 // End Of Image.
const val MARKER_SOS = 0xDA // Start Of Scan.
const val MARKER_DQT = 0xDB // Define Quantization Table.
const val MARKER_DNL = 0xDC // Define Number of Lines.
const val MARKER_DRI = 0xDD // Define Restart Interval.
const val MARKER_APP0 = 0xE0 // JFIF lives here.
const val MARKER_APP14 = 0xEE // Adobe color-transform marker lives here.
const val MARKER_APP15 = 0xEF
const val MARKER_COM = 0xFE // Comment.
const val MARKER_RST0 = 0xD0 // Restart markers RST0..RST7.
const val MARKER_RST7 = 0xD7
/** Samples per DCT block edge; the JPEG block is always 8x8 (T.81 A.3.3). */
const val BLOCK_SIZE = 8
/** Coefficients per DCT block. */
const val BLOCK_COEFFICIENTS = 64
/**
* Maps a zig-zag coefficient index to its natural (row-major) index within an 8x8 block.
*
* DQT tables and entropy-coded coefficients both arrive in zig-zag order; storing them through
* this table puts both in natural order, which is what the IDCT indexes.
*/
val NATURAL_ORDER =
intArrayOf(
0,
1,
8,
16,
9,
2,
3,
10,
17,
24,
32,
25,
18,
11,
4,
5,
12,
19,
26,
33,
40,
48,
41,
34,
27,
20,
13,
6,
7,
14,
21,
28,
35,
42,
49,
56,
57,
50,
43,
36,
29,
22,
15,
23,
30,
37,
44,
51,
58,
59,
52,
45,
38,
31,
39,
46,
53,
60,
61,
54,
47,
55,
62,
63,
)
/**
* True when [marker] is any Start Of Frame code (the SOFn range excluding DHT/DAC/RSTn).
*
* @param Int marker The marker code (the byte following 0xFF).
* @return Boolean Whether the marker starts a frame.
*/
fun isStartOfFrame(marker: Int): Boolean =
marker == MARKER_SOF0 ||
marker == MARKER_SOF1 ||
marker == MARKER_SOF2 ||
marker == MARKER_SOF3 ||
marker == MARKER_SOF5 ||
marker == MARKER_SOF6 ||
marker == MARKER_SOF7 ||
marker == MARKER_SOF9 ||
marker == MARKER_SOF10 ||
marker == MARKER_SOF11 ||
marker == MARKER_SOF13 ||
marker == MARKER_SOF14 ||
marker == MARKER_SOF15
/**
* Names an undecodable Start Of Frame, for the rejection message.
*
* Only reachable for frame types outside SOF0/SOF1/SOF2, so every case here is arithmetic-coded,
* differential, or lossless.
*
* @param Int marker The SOFn marker code.
* @return String The frame type's name.
*/
fun startOfFrameDescription(marker: Int): String =
when (marker) {
MARKER_SOF3 -> "lossless JPEG (SOF3)"
MARKER_SOF5 -> "differential sequential JPEG (SOF5)"
MARKER_SOF6 -> "differential progressive JPEG (SOF6)"
MARKER_SOF7 -> "differential lossless JPEG (SOF7)"
MARKER_SOF9 -> "arithmetic-coded sequential JPEG (SOF9)"
MARKER_SOF10 -> "arithmetic-coded progressive JPEG (SOF10)"
MARKER_SOF11 -> "arithmetic-coded lossless JPEG (SOF11)"
MARKER_SOF13 -> "arithmetic-coded differential sequential JPEG (SOF13)"
MARKER_SOF14 -> "arithmetic-coded differential progressive JPEG (SOF14)"
MARKER_SOF15 -> "arithmetic-coded differential lossless JPEG (SOF15)"
else -> "JPEG frame type 0x${marker.toString(16).uppercase()}"
}
}
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,191 @@
// Baseline JPEG entropy decoding: the MSB-first bit reader with 0xFF00 byte de-stuffing (T.81 F.1.2.1)
// and the canonical Huffman DECODE procedure (T.81 Annex F, Figures F.12 / F.16).
package org.umamo.format.jpeg
/**
* A canonical JPEG Huffman table, built from a DHT segment's per-length code counts and value list.
*
* Decoding follows T.81 Figure F.16: walk one bit at a time, growing the code until it falls within
* the [minCode]/[maxCode] range recorded for the current code length.
*/
internal class JpegHuffmanTable(codeCountsPerLength: IntArray, private val values: IntArray) {
// Indexed by code length 1..16; index 0 is unused so the spec's 1-based lengths read directly.
private val minCode = IntArray(17)
private val maxCode = IntArray(17)
private val valuePointer = IntArray(17)
init {
// T.81 Figure F.15: assign canonical codes in increasing length, then increasing value order.
var code = 0
var valueIndex = 0
for (codeLength in 1..16) {
val countAtLength = codeCountsPerLength[codeLength - 1]
if (countAtLength == 0) {
// No codes of this length; the sentinel makes the DECODE comparison always fall through.
maxCode[codeLength] = -1
} else {
valuePointer[codeLength] = valueIndex
minCode[codeLength] = code
valueIndex += countAtLength
code += countAtLength
maxCode[codeLength] = code - 1
}
code = code shl 1
}
}
/**
* Decodes one Huffman-coded symbol.
*
* @param JpegBitReader reader The entropy-coded bit source.
* @return Int The decoded symbol value.
*/
fun decode(reader: JpegBitReader): Int {
var code = reader.readBit()
var codeLength = 1
while (code > maxCode[codeLength]) {
code = (code shl 1) or reader.readBit()
codeLength++
require(codeLength <= 16) { "Invalid JPEG Huffman code (longer than 16 bits)" }
}
val index = valuePointer[codeLength] + code - minCode[codeLength]
require(index in values.indices) { "Invalid JPEG Huffman code (value index $index out of range)" }
return values[index]
}
}
/**
* An MSB-first bit reader over JPEG entropy-coded data.
*
* Handles the 0xFF00 stuffed-zero convention (T.81 F.1.2.3). On reaching a real marker or the end of
* the buffer the reader pads with zero bits rather than failing, matching libjpeg's behavior for
* truncated scans; [markerReached] reports that the entropy segment has ended.
*/
internal class JpegBitReader(private val data: ByteArray, position: Int) {
/** The read cursor, left pointing at the 0xFF of a marker once one is reached. */
var position: Int = position
private set
/** True once a marker or the end of the buffer has been reached and bits are being zero-padded. */
var markerReached: Boolean = false
private set
private var bitBuffer = 0
private var bitCount = 0
/**
* Reads the next entropy-coded bit, MSB first.
*
* @return Int The bit value (0 or 1); zero once the entropy segment has ended.
*/
fun readBit(): Int {
if (bitCount == 0) {
if (!fillBitBuffer()) {
return 0
}
}
bitCount--
return (bitBuffer shr bitCount) and 1
}
/**
* Reads [count] bits as an unsigned value, MSB first (the T.81 RECEIVE procedure, Figure F.17).
*
* @param Int count The number of bits to read (0..16).
* @return Int The bits as an unsigned integer.
*/
fun readBits(count: Int): Int {
var value = 0
for (bitIndex in 0 until count) {
value = (value shl 1) or readBit()
}
return value
}
/**
* Loads the next entropy-coded byte into the bit buffer, de-stuffing 0xFF00.
*
* @return Boolean False when a marker or the buffer end stopped the fill (bits are zero-padded).
*/
private fun fillBitBuffer(): Boolean {
if (position >= data.size) {
markerReached = true
return false
}
var nextByte = data[position].toInt() and 0xFF
if (nextByte == 0xFF) {
// Skip any fill bytes preceding a marker (T.81 B.1.1.2 permits 0xFF padding).
var lookahead = position + 1
while (lookahead < data.size && (data[lookahead].toInt() and 0xFF) == 0xFF) {
lookahead++
}
if (lookahead >= data.size) {
position = data.size
markerReached = true
return false
}
val following = data[lookahead].toInt() and 0xFF
if (following != 0x00) {
// A real marker: leave the cursor on its 0xFF so the caller can identify it.
position = lookahead - 1
markerReached = true
return false
}
// A stuffed zero: the 0xFF is literal data and the 0x00 is dropped.
position = lookahead + 1
nextByte = 0xFF
} else {
position++
}
bitBuffer = nextByte
bitCount = 8
return true
}
/**
* Discards buffered bits and consumes the next restart marker, per T.81 F.2.1.3.1.
*
* @return Boolean Whether a restart marker was found and consumed.
*/
fun restart(): Boolean {
bitCount = 0
markerReached = false
// The marker should sit at the cursor once bits are dropped, but tolerate stray fill bytes.
var scan = position
while (scan + 1 < data.size) {
if ((data[scan].toInt() and 0xFF) == 0xFF) {
val marker = data[scan + 1].toInt() and 0xFF
if (marker in JpegConstants.MARKER_RST0..JpegConstants.MARKER_RST7) {
position = scan + 2
return true
}
if (marker != 0xFF && marker != 0x00) {
// Some other marker: the scan is over, leave the cursor for the caller.
position = scan
markerReached = true
return false
}
}
scan++
}
position = data.size
markerReached = true
return false
}
}
/**
* Sign-extends a [length]-bit Huffman-coded difference value (the T.81 EXTEND procedure, Figure F.12).
*
* @param Int value The raw magnitude bits from RECEIVE.
* @param Int length The number of bits read.
* @return Int The signed coefficient difference.
*/
internal fun extendJpegValue(value: Int, length: Int): Int {
if (length == 0) {
return 0
}
// Values whose top bit is clear encode the negative half of the range.
return if (value < (1 shl (length - 1))) value - (1 shl length) + 1 else value
}
@@ -0,0 +1,220 @@
// Inverse DCT for baseline JPEG: the accurate integer ("islow") variant from the Independent JPEG
// Group's jidctint.c, a slow-but-exact 13-bit fixed-point implementation of the AAN-style separable
// IDCT described in T.81 Annex A.3.3. Implemented faithfully because the fixed-point rounding IS the
// output: libjpeg (and libjpeg-turbo, whose SIMD path is bit-exact with this C code) produce these
// exact samples, so a faithful port decodes byte-identically to every mainstream JPEG reader.
package org.umamo.format.jpeg
/**
* The 8x8 inverse DCT, integer "islow" variant.
*
* Pass 1 transforms columns into a workspace scaled up by 2^PASS1_BITS; pass 2 transforms rows and
* descales, level-shifts by +128, and clamps to 0..255.
*/
internal object JpegIdct {
// Fixed-point precision. CONST_BITS is the multiplier scale; PASS1_BITS the inter-pass headroom.
private const val CONST_BITS = 13
private const val PASS1_BITS = 2
// Cosine multipliers, each round(value * 2^CONST_BITS). Names carry the value they approximate.
private const val FIX_0_298631336 = 2446
private const val FIX_0_390180644 = 3196
private const val FIX_0_541196100 = 4433
private const val FIX_0_765366865 = 6270
private const val FIX_0_899976223 = 7373
private const val FIX_1_175875602 = 9633
private const val FIX_1_501321110 = 12299
private const val FIX_1_847759065 = 15137
private const val FIX_1_961570560 = 16069
private const val FIX_2_053119869 = 16819
private const val FIX_2_562915447 = 20995
private const val FIX_3_072711026 = 25172
/**
* Rounds a fixed-point value down by [shift] bits, rounding half away from zero-ward as libjpeg does.
*
* @param Int value The scaled value.
* @param Int shift The number of fractional bits to drop.
* @return Int The descaled value.
*/
private fun descale(value: Int, shift: Int): Int = (value + (1 shl (shift - 1))) shr shift
/**
* Performs the inverse DCT of one block, writing level-shifted, clamped 8-bit samples.
*
* @param IntArray coefficients 64 dequantized coefficients in natural (row-major) order.
* @param IntArray workspace A scratch buffer of at least 64 ints, reused across calls.
* @param ByteArray output The destination plane.
* @param Int outputOffset Index in [output] of the block's top-left sample.
* @param Int outputStride Distance in [output] between vertically adjacent samples.
*/
fun inverse(coefficients: IntArray, workspace: IntArray, output: ByteArray, outputOffset: Int, outputStride: Int) {
// Pass 1: columns. Results are scaled up by sqrt(8) * 2^PASS1_BITS relative to a true IDCT.
for (column in 0 until 8) {
// Most blocks have all-zero AC terms in a column; that column is then a flat DC value.
if (coefficients[column + 8] == 0 &&
coefficients[column + 16] == 0 &&
coefficients[column + 24] == 0 &&
coefficients[column + 32] == 0 &&
coefficients[column + 40] == 0 &&
coefficients[column + 48] == 0 &&
coefficients[column + 56] == 0
) {
val dcValue = coefficients[column] shl PASS1_BITS
for (row in 0 until 8) {
workspace[column + row * 8] = dcValue
}
continue
}
// Even part: the rotator is sqrt(2) * c(-6).
var z2 = coefficients[column + 16]
var z3 = coefficients[column + 48]
var z1 = (z2 + z3) * FIX_0_541196100
var tmp2 = z1 + z3 * -FIX_1_847759065
var tmp3 = z1 + z2 * FIX_0_765366865
z2 = coefficients[column]
z3 = coefficients[column + 32]
var tmp0 = (z2 + z3) shl CONST_BITS
var tmp1 = (z2 - z3) shl CONST_BITS
val tmp10 = tmp0 + tmp3
val tmp13 = tmp0 - tmp3
val tmp11 = tmp1 + tmp2
val tmp12 = tmp1 - tmp2
// Odd part: i0..i3 are coefficients 7, 5, 3, 1.
tmp0 = coefficients[column + 56]
tmp1 = coefficients[column + 40]
tmp2 = coefficients[column + 24]
tmp3 = coefficients[column + 8]
z1 = tmp0 + tmp3
z2 = tmp1 + tmp2
z3 = tmp0 + tmp2
var z4 = tmp1 + tmp3
val z5 = (z3 + z4) * FIX_1_175875602 // sqrt(2) * c3
tmp0 *= FIX_0_298631336 // sqrt(2) * (-c1+c3+c5-c7)
tmp1 *= FIX_2_053119869 // sqrt(2) * ( c1+c3-c5+c7)
tmp2 *= FIX_3_072711026 // sqrt(2) * ( c1+c3+c5-c7)
tmp3 *= FIX_1_501321110 // sqrt(2) * ( c1+c3-c5-c7)
z1 *= -FIX_0_899976223 // sqrt(2) * (c7-c3)
z2 *= -FIX_2_562915447 // sqrt(2) * (-c1-c3)
z3 *= -FIX_1_961570560 // sqrt(2) * (-c3-c5)
z4 *= -FIX_0_390180644 // sqrt(2) * (c5-c3)
z3 += z5
z4 += z5
tmp0 += z1 + z3
tmp1 += z2 + z4
tmp2 += z2 + z3
tmp3 += z1 + z4
workspace[column] = descale(tmp10 + tmp3, CONST_BITS - PASS1_BITS)
workspace[column + 56] = descale(tmp10 - tmp3, CONST_BITS - PASS1_BITS)
workspace[column + 8] = descale(tmp11 + tmp2, CONST_BITS - PASS1_BITS)
workspace[column + 48] = descale(tmp11 - tmp2, CONST_BITS - PASS1_BITS)
workspace[column + 16] = descale(tmp12 + tmp1, CONST_BITS - PASS1_BITS)
workspace[column + 40] = descale(tmp12 - tmp1, CONST_BITS - PASS1_BITS)
workspace[column + 24] = descale(tmp13 + tmp0, CONST_BITS - PASS1_BITS)
workspace[column + 32] = descale(tmp13 - tmp0, CONST_BITS - PASS1_BITS)
}
// Pass 2: rows. Descale by the pass-1 scale plus the IDCT's own factor of 8 (2^3).
for (row in 0 until 8) {
val rowBase = row * 8
val outputRow = outputOffset + row * outputStride
// Pass 1 fills in AC terms, so the all-zero shortcut hits far less often here, but it is cheap.
if (workspace[rowBase + 1] == 0 &&
workspace[rowBase + 2] == 0 &&
workspace[rowBase + 3] == 0 &&
workspace[rowBase + 4] == 0 &&
workspace[rowBase + 5] == 0 &&
workspace[rowBase + 6] == 0 &&
workspace[rowBase + 7] == 0
) {
val dcSample = clampToSample(descale(workspace[rowBase], PASS1_BITS + 3))
for (column in 0 until 8) {
output[outputRow + column] = dcSample
}
continue
}
// Even part: the rotator is sqrt(2) * c(-6).
var z2 = workspace[rowBase + 2]
var z3 = workspace[rowBase + 6]
var z1 = (z2 + z3) * FIX_0_541196100
var tmp2 = z1 + z3 * -FIX_1_847759065
var tmp3 = z1 + z2 * FIX_0_765366865
var tmp0 = (workspace[rowBase] + workspace[rowBase + 4]) shl CONST_BITS
var tmp1 = (workspace[rowBase] - workspace[rowBase + 4]) shl CONST_BITS
val tmp10 = tmp0 + tmp3
val tmp13 = tmp0 - tmp3
val tmp11 = tmp1 + tmp2
val tmp12 = tmp1 - tmp2
// Odd part: i0..i3 are coefficients 7, 5, 3, 1.
tmp0 = workspace[rowBase + 7]
tmp1 = workspace[rowBase + 5]
tmp2 = workspace[rowBase + 3]
tmp3 = workspace[rowBase + 1]
z1 = tmp0 + tmp3
z2 = tmp1 + tmp2
z3 = tmp0 + tmp2
var z4 = tmp1 + tmp3
val z5 = (z3 + z4) * FIX_1_175875602 // sqrt(2) * c3
tmp0 *= FIX_0_298631336
tmp1 *= FIX_2_053119869
tmp2 *= FIX_3_072711026
tmp3 *= FIX_1_501321110
z1 *= -FIX_0_899976223
z2 *= -FIX_2_562915447
z3 *= -FIX_1_961570560
z4 *= -FIX_0_390180644
z3 += z5
z4 += z5
tmp0 += z1 + z3
tmp1 += z2 + z4
tmp2 += z2 + z3
tmp3 += z1 + z4
output[outputRow] = clampToSample(descale(tmp10 + tmp3, CONST_BITS + PASS1_BITS + 3))
output[outputRow + 7] = clampToSample(descale(tmp10 - tmp3, CONST_BITS + PASS1_BITS + 3))
output[outputRow + 1] = clampToSample(descale(tmp11 + tmp2, CONST_BITS + PASS1_BITS + 3))
output[outputRow + 6] = clampToSample(descale(tmp11 - tmp2, CONST_BITS + PASS1_BITS + 3))
output[outputRow + 2] = clampToSample(descale(tmp12 + tmp1, CONST_BITS + PASS1_BITS + 3))
output[outputRow + 5] = clampToSample(descale(tmp12 - tmp1, CONST_BITS + PASS1_BITS + 3))
output[outputRow + 3] = clampToSample(descale(tmp13 + tmp0, CONST_BITS + PASS1_BITS + 3))
output[outputRow + 4] = clampToSample(descale(tmp13 - tmp0, CONST_BITS + PASS1_BITS + 3))
}
}
/**
* Applies the JPEG level shift (+128) and clamps to an 8-bit sample.
*
* libjpeg reads a precomputed range-limit table here; for in-range coefficients that table is
* exactly this clamp, and out-of-range values only arise from corrupt data.
*
* @param Int value The descaled, zero-centered IDCT output.
* @return Byte The 0..255 sample.
*/
private fun clampToSample(value: Int): Byte {
val shifted = value + 128
return when {
shifted < 0 -> 0
shifted > 255 -> 255.toByte()
else -> shifted.toByte()
}
}
}
@@ -0,0 +1,73 @@
package org.umamo.format.jpeg
import org.umamo.format.FileKind
import org.umamo.format.raster.RasterImage
import org.umamo.format.raster.ReadOnlyRasterCodec
/**
* Pure-Kotlin JPEG reader (desktop JVM and Android), read only.
*
* Decodes sequential (SOF0 / SOF1) and progressive (SOF2) Huffman JPEG, 8-bit, grayscale or
* 3-component color, with restart intervals and any sampling factors, to the neutral straight-alpha
* RGBA8888 top-first [RasterImage] (alpha is always opaque — JPEG carries no alpha channel).
* Progressive support matters in practice, not as a nicety: it is what most of the web serves, so the
* common art sources (Twitter/X, Pixiv, Photoshop "Save for Web") emit it by default.
*
* Lossless, arithmetic-coded, differential, 12-bit, and CMYK/YCCK frames are rejected with a clear
* message. Uses no javax.imageio, so it decodes identically on both targets.
*/
public object JpegReader : ReadOnlyRasterCodec {
override val kind: FileKind = FileKind.Jpeg
/**
* True if [candidateBytes] opens with the JPEG SOI + marker prefix.
*
* @param ByteArray candidateBytes Candidate file contents.
* @return Boolean Whether the leading bytes are the JPEG magic.
*/
override fun matches(candidateBytes: ByteArray): Boolean =
// JPEG (JFIF/EXIF): SOI marker 0xFFD8 followed by a further 0xFF marker byte.
candidateBytes.size >= 3 &&
candidateBytes[0] == 0xFF.toByte() &&
candidateBytes[1] == 0xD8.toByte() &&
candidateBytes[2] == 0xFF.toByte()
/**
* Decodes a `.jpg` into an opaque straight-alpha RGBA8888 [RasterImage], top row first.
*
* @param ByteArray bytes The complete `.jpg` file.
* @return RasterImage The decoded image.
*/
override fun read(bytes: ByteArray): RasterImage {
require(matches(bytes)) { "Not a JPEG (bad signature)" }
val decoded = decodeJpeg(bytes)
return RasterImage(decoded.width, decoded.height, expandToRgba(decoded))
}
/**
* Expands decoded grayscale or RGB samples to opaque RGBA8888.
*
* @param JpegImage decoded The decoded JPEG.
* @return ByteArray The RGBA8888 pixels.
*/
private fun expandToRgba(decoded: JpegImage): ByteArray {
val pixelCount = decoded.width * decoded.height
val rgba = ByteArray(pixelCount * 4)
for (pixelIndex in 0 until pixelCount) {
val destination = pixelIndex * 4
if (decoded.componentCount == 1) {
val gray = decoded.samples[pixelIndex]
rgba[destination] = gray
rgba[destination + 1] = gray
rgba[destination + 2] = gray
} else {
val source = pixelIndex * 3
rgba[destination] = decoded.samples[source]
rgba[destination + 1] = decoded.samples[source + 1]
rgba[destination + 2] = decoded.samples[source + 2]
}
rgba[destination + 3] = 0xFF.toByte()
}
return rgba
}
}
@@ -0,0 +1,48 @@
package org.umamo.format.kra
import org.umamo.format.art.ChannelMask
/*
* The channelflags -> ChannelMask mapping, split out of KraReader so it can live in commonMain.
*
* KraReader itself cannot: it is a zip container plus a JDOM/SAX XML parse, both JVM-only, so it
* stays in jvmAndroidMain alongside the FormatRegistry that is its only non-test caller. This
* mapping is pure arithmetic over a string and belongs with the rest of KRA's platform-free logic
* (KraColorModel, KraLzf, KraTileData), where KraChannelMaskTest can reach it from commonTest and
* exercise it on every target.
*/
/**
* Builds the neutral per-channel mask from Krita's channelflags attribute.
*
* channelflags is a per-channel enable mask in channel-index order ('0' disables a channel,
* anything else enables it; indices beyond the string default to enabled), or empty meaning all
* channels enabled. The channel-index order is the color space's own: for RGB it is Blue, Green,
* Red, Alpha (the addChannel sequence in RgbU8ColorSpace.cpp), and for GRAYA it is Gray, Alpha.
* Grayscale's single gray channel maps onto R, G, and B together, because the raster expands gray
* to RGB.
*
* A disabled alpha is Krita's "Inherit Alpha", which the caller maps onto the neutral clipped flag.
* That clipping is an approximation: PSD clips to the single base layer directly below, whereas
* Krita clips to the composite of everything below in the group.
*
* @param String? channelFlags The layer's channelflags attribute (null/empty means all enabled).
* @param KraPixelFormat format The resolved pixel format (gives channel family and order).
* @return ChannelMask the enabled state of the output red/green/blue/alpha channels.
*/
internal fun channelMaskFrom(channelFlags: String?, format: KraPixelFormat): ChannelMask {
// KRA: kis_kra_utils.cpp stringToFlags ('0' disables, default enabled); channel order from the
// color space addChannel sequence (RgbU8ColorSpace.cpp / GrayU8ColorSpace.cpp).
if (channelFlags.isNullOrEmpty()) {
return ChannelMask.ALL
}
fun channelEnabled(channelIndex: Int): Boolean =
channelIndex !in channelFlags.indices || channelFlags[channelIndex] != '0'
return if (format.isRgb) {
ChannelMask(red = channelEnabled(2), green = channelEnabled(1), blue = channelEnabled(0), alpha = channelEnabled(3))
} else {
val grayEnabled = channelEnabled(0)
ChannelMask(red = grayEnabled, green = grayEnabled, blue = grayEnabled, alpha = channelEnabled(1))
}
}
@@ -0,0 +1,171 @@
package org.umamo.format.kra
/**
* Maps a Krita layer's color space onto a converter that packs each source pixel into the neutral
* model's RGBA8888 straight-alpha format.
*
* Two things vary between Krita color spaces and must be handled here. First, channel byte order:
* Krita's integer RGB spaces store BGRA (KoBgrU8Traits / KoBgrU16Traits with blue at 0, green at 1,
* red at 2), while its float RGB space stores RGBA (KoRgbColorSpaceTraits with red at 0, green at 1,
* blue at 2). Grayscale is gray then alpha (KoGrayColorSpaceTraits). Second, bit depth: 8/16-bit
* integer and 32-bit float, down-converted to 8-bit (16-bit keeps the most-significant byte; float
* is clamped to 0..1 and scaled). The model is always RGBA8888, so high-depth precision cannot be
* preserved regardless - this is lossy by the model's contract.
*
* Scope: RGBA and GRAYA in U8, U16, and F32. Half-float (F16) and other models (CMYK, LAB, XYZ,
* YCbCr) raise a clear error rather than silently mis-decoding.
*
* Krita のカラースペースを RGBA8888 へ変換する。整数 RGB は BGRA、浮動小数 RGB は RGBA、グレースケールは
* gray, alpha の順。8/16/32 ビットに対応し 8 ビットへ縮約する。
*/
internal enum class KraColorDepth {
UnsignedByte, // U8
UnsignedShort, // U16
Float32, // F32
}
/**
* A resolved per-layer pixel layout plus the logic to convert one source pixel to RGBA8888.
*
* @property Int channelCount Channels in the source pixel (RGBA is 4, GRAYA is 2).
* @property KraColorDepth depth Source bit depth.
* @property Boolean isRgb True for the RGBA family, false for GRAYA.
*/
internal class KraPixelFormat(
val channelCount: Int,
val depth: KraColorDepth,
val isRgb: Boolean,
) {
val bytesPerChannel: Int =
when (depth) {
KraColorDepth.UnsignedByte -> 1
KraColorDepth.UnsignedShort -> 2
KraColorDepth.Float32 -> 4
}
/** Bytes per source pixel - must equal the tile file's PIXELSIZE. */
val pixelSize: Int = channelCount * bytesPerChannel
/**
* Converts the source pixel at sourceOffset in source to four RGBA8888 bytes written at
* destinationOffset in destination.
*
* @param ByteArray source Interleaved native-order pixel bytes (one tile or row).
* @param Int sourceOffset Byte offset of the source pixel.
* @param ByteArray destination RGBA8888 output buffer.
* @param Int destinationOffset Byte offset of the destination pixel (4 bytes written).
*/
fun convertPixel(
source: ByteArray,
sourceOffset: Int,
destination: ByteArray,
destinationOffset: Int,
) {
if (isRgb) {
when (depth) {
// KRA: KoBgrU8Traits - blue at 0, green at 1, red at 2, alpha at 3.
KraColorDepth.UnsignedByte -> {
destination[destinationOffset] = source[sourceOffset + 2] // red
destination[destinationOffset + 1] = source[sourceOffset + 1] // green
destination[destinationOffset + 2] = source[sourceOffset] // blue
destination[destinationOffset + 3] = source[sourceOffset + 3] // alpha
}
// KRA: KoBgrU16Traits - BGRA, little-endian; keep the MSB (offset+1 of each pair).
KraColorDepth.UnsignedShort -> {
destination[destinationOffset] = source[sourceOffset + 5] // red MSB
destination[destinationOffset + 1] = source[sourceOffset + 3] // green MSB
destination[destinationOffset + 2] = source[sourceOffset + 1] // blue MSB
destination[destinationOffset + 3] = source[sourceOffset + 7] // alpha MSB
}
// KRA: KoRgbColorSpaceTraits - float RGB is red-first (RGBA), 32-bit little-endian.
KraColorDepth.Float32 -> {
destination[destinationOffset] = floatByteToUnorm8(source, sourceOffset) // red
destination[destinationOffset + 1] = floatByteToUnorm8(source, sourceOffset + 4) // green
destination[destinationOffset + 2] = floatByteToUnorm8(source, sourceOffset + 8) // blue
destination[destinationOffset + 3] = floatByteToUnorm8(source, sourceOffset + 12) // alpha
}
}
} else {
// Grayscale: replicate the single grey channel into R/G/B. KRA: KoGrayColorSpaceTraits.
val grayByte: Byte
val alphaByte: Byte
when (depth) {
KraColorDepth.UnsignedByte -> {
grayByte = source[sourceOffset]
alphaByte = source[sourceOffset + 1]
}
KraColorDepth.UnsignedShort -> {
grayByte = source[sourceOffset + 1] // gray MSB
alphaByte = source[sourceOffset + 3] // alpha MSB
}
KraColorDepth.Float32 -> {
grayByte = floatByteToUnorm8(source, sourceOffset)
alphaByte = floatByteToUnorm8(source, sourceOffset + 4)
}
}
destination[destinationOffset] = grayByte
destination[destinationOffset + 1] = grayByte
destination[destinationOffset + 2] = grayByte
destination[destinationOffset + 3] = alphaByte
}
}
}
/**
* Reads a 32-bit little-endian float at offset in source and quantises it to an 8-bit unorm byte
* (clamped to 0..1, scaled by 255, rounded).
*
* @param ByteArray source Buffer holding the float.
* @param Int offset Byte offset of the 4-byte little-endian float.
* @return Byte the quantised 0..255 channel value (as a signed Byte).
*/
private fun floatByteToUnorm8(source: ByteArray, offset: Int): Byte {
val bits =
(source[offset].toInt() and 0xFF) or
((source[offset + 1].toInt() and 0xFF) shl 8) or
((source[offset + 2].toInt() and 0xFF) shl 16) or
((source[offset + 3].toInt() and 0xFF) shl 24)
val value = Float.fromBits(bits)
val clamped = value.coerceIn(0f, 1f)
return (clamped * 255f + 0.5f).toInt().toByte()
}
/**
* Resolves a Krita colorspacename (such as RGBA, RGBA16, RGBAF32, or GRAYA) to a KraPixelFormat,
* cross-checking the implied pixel size against the tile file's authoritative PIXELSIZE.
*
* Family comes from the prefix (RGBA or GRAYA) and depth from a suffix scan (F32 means float, F16
* is unsupported, any 16 means uint16, otherwise uint8) - robust across Krita's historically
* inconsistent names without enumerating every exact string.
*
* @param String colorspaceName The layer's colorspacename attribute.
* @param Int tilePixelSize Bytes per pixel from the tile header (PIXELSIZE).
* @return KraPixelFormat the resolved layout and converter.
* @throws IllegalArgumentException on an unsupported model/depth or a size mismatch.
*/
internal fun resolveKraPixelFormat(colorspaceName: String, tilePixelSize: Int): KraPixelFormat {
val normalized = colorspaceName.uppercase()
val isRgb = normalized.startsWith("RGBA")
val isGray = normalized.startsWith("GRAYA")
require(isRgb || isGray) {
"Unsupported KRA color model '$colorspaceName' - only RGBA and GRAYA are supported"
}
val depth =
when {
normalized.contains("F32") -> KraColorDepth.Float32
normalized.contains("F16") ->
error("Unsupported KRA color depth (half-float) '$colorspaceName'")
normalized.contains("16") -> KraColorDepth.UnsignedShort
else -> KraColorDepth.UnsignedByte
}
val format = KraPixelFormat(channelCount = if (isRgb) 4 else 2, depth = depth, isRgb = isRgb)
require(format.pixelSize == tilePixelSize) {
"KRA pixel-size mismatch: tile header says $tilePixelSize, '$colorspaceName' implies ${format.pixelSize}"
}
return format
}
@@ -0,0 +1,138 @@
package org.umamo.format.kra
/*
* Krita tile (de)serialisation primitives: the LZF decompressor and the color "delinearisation"
* that together reverse what Krita writes for each 64x64 tile.
*
* Krita compresses tile pixels with a fast LZF variant (a Lempel-Ziv byte coder), and - before
* compressing - reorders the interleaved pixel bytes into a planar layout (all of channel 0, then
* all of channel 1, and so on) because runs of one channel compress far better. Reading is the
* mirror: LZF-decompress, then de-interleave back to packed pixels.
*
* Pure Kotlin with no platform APIs, so it lives below the ZIP/XML orchestration and is unit
* testable on its own. Ported verbatim from Krita's GPL source.
*
* Krita タイルの復号プリミティブ。LZF 伸長と平面→インターリーブ変換。プラットフォーム非依存。
*/
// KRA: kis_tile_compressor_2.cpp - first payload byte selects raw vs LZF-compressed tile data.
internal const val KRA_RAW_DATA_FLAG: Int = 0
internal const val KRA_COMPRESSED_DATA_FLAG: Int = 1
/**
* Decompresses one LZF stream into output, a direct port of Krita's lzff_decompress.
*
* The coder emits a stream of control bytes. A control byte whose value is below 32 starts a
* literal run of value-plus-one raw bytes; otherwise its top 3 bits are a back-reference length and
* its low 5 bits are the high bits of a back-reference distance (the next byte carries the low 8
* bits, and a length of 7 means "read one more byte and add it"). Back-references copy
* already-decoded bytes, so output must be written strictly left to right.
*
* @param ByteArray input Buffer holding the compressed stream.
* @param Int inputOffset Index in input where the stream starts (skip the flag byte).
* @param Int inputLength Number of compressed bytes to read from inputOffset.
* @param ByteArray output Destination for the decoded bytes (sized to the exact tile size).
* @return Int the number of bytes written to output; 0 on a malformed or overrunning stream.
*/
internal fun lzfDecompress(
input: ByteArray,
inputOffset: Int,
inputLength: Int,
output: ByteArray,
): Int {
var inputPos = inputOffset
// KRA: kis_lzf_compression.cpp:176 - ip_limit = ip + length - 1 (last byte is never a header).
val inputLimit = inputOffset + inputLength - 1
var outputPos = 0
val outputLimit = output.size
while (inputPos < inputLimit) {
// KRA: kis_lzf_compression.cpp:182-184 - control byte; all three values read the same byte.
val control = input[inputPos].toInt() and 0xFF
inputPos++
val literalRunLength = control + 1 // The "ctrl" value: byte count when this is a literal run.
var backReferenceLength = control ushr 5
if (literalRunLength < 33) {
// Literal copy of literalRunLength raw bytes. KRA: kis_lzf_compression.cpp:186-208.
if (outputPos + literalRunLength > outputLimit) {
return 0
}
var remaining = literalRunLength
while (remaining > 0) {
output[outputPos] = input[inputPos]
outputPos++
inputPos++
remaining--
}
} else {
// Back reference. KRA: kis_lzf_compression.cpp:209-232.
backReferenceLength -= 1
// ref = op - ofs; ref-- where ofs = (control & 31) << 8.
var referencePos = outputPos - ((control and 31) shl 8) - 1
if (backReferenceLength == 6) {
backReferenceLength += input[inputPos].toInt() and 0xFF
inputPos++
}
referencePos -= input[inputPos].toInt() and 0xFF
inputPos++
if (outputPos + backReferenceLength + 3 > outputLimit) {
return 0
}
if (referencePos < 0) {
return 0
}
// 3 bytes always, then backReferenceLength more (the length is biased by 3).
output[outputPos] = output[referencePos]
outputPos++
referencePos++
output[outputPos] = output[referencePos]
outputPos++
referencePos++
output[outputPos] = output[referencePos]
outputPos++
referencePos++
while (backReferenceLength > 0) {
output[outputPos] = output[referencePos]
outputPos++
referencePos++
backReferenceLength--
}
}
}
return outputPos
}
/**
* Reverses Krita's color "linearisation": turns a planar buffer (channel 0 for every pixel, then
* channel 1, and so on) back into packed interleaved pixels (b,g,r,a,b,g,r,a and onward).
*
* Mirror of KisAbstractCompression::delinearizeColors: with stride equal to dataSize / pixelSize
* (the pixel count), output byte pixel * pixelSize + channel reads input byte channelstride + pixel.
* Only compressed tiles are linearised; raw tiles are already interleaved.
*
* @param ByteArray planarInput The de-compressed, planar tile bytes.
* @param ByteArray packedOutput Destination for interleaved pixels (same length as planarInput).
* @param Int dataSize Total byte count (pixelSize * tileWidth * tileHeight).
* @param Int pixelSize Bytes per pixel (channel count times bytes per channel).
*/
internal fun delinearizeColors(
planarInput: ByteArray,
packedOutput: ByteArray,
dataSize: Int,
pixelSize: Int,
) {
// KRA: kis_abstract_compression.cpp:38-66 - stride is the per-channel run length (pixel count).
val strideSize = dataSize / pixelSize
var outputPos = 0
var pixelStartByte = 0
while (outputPos < dataSize) {
var inputPos = pixelStartByte
for (channelIndex in 0 until pixelSize) {
packedOutput[outputPos] = planarInput[inputPos]
outputPos++
inputPos += strideSize
}
pixelStartByte++
}
}
@@ -0,0 +1,185 @@
package org.umamo.format.kra
import org.umamo.format.binary.decodeAscii
/*
* Parser for one Krita layer's tiled pixel-data file (the imageName/layers/filename entry inside
* the ZIP).
*
* The file is a tiny ASCII header followed by a sequence of tiles. Each tile is a 64x64 block at a
* given paint-device coordinate; a tile is present only where the layer has content (Krita's canvas
* is unbounded), so the layer's extent is the union of its tile rectangles.
*
* The header is one KEY VALUE pair per newline-terminated line, in this order: VERSION 2,
* TILEWIDTH 64, TILEHEIGHT 64, PIXELSIZE bytesPerPixel, DATA tileCount. Each tile then has a line
* x,y,LZF,dataSize followed by dataSize bytes whose first byte flags raw vs LZF-compressed payload
* (see decodeTilePayload).
*
* KRA: header in kis_tiled_data_manager.cc:181-196; per-tile framing in kis_tile_compressor_2.cpp.
*
* Krita レイヤーのタイル化ピクセルデータの解析。ASCII ヘッダとタイル列。タイルは内容のある箇所のみ存在する。
*/
/** One decoded 64x64 tile: its top-left paint-device coordinate and interleaved native-order pixels. */
internal class KraTile(
val left: Int,
val top: Int,
val pixels: ByteArray,
)
/** A layer's full tile set plus the geometry needed to assemble it. */
internal class KraLayerTiles(
val tileWidth: Int,
val tileHeight: Int,
val pixelSize: Int,
val tiles: List<KraTile>,
)
/**
* Parses a layer data file into its decoded tiles (each tile's pixels are interleaved, native
* channel order - color conversion happens later, once the layer's KraPixelFormat is known).
*
* @param ByteArray data The complete layer data file bytes.
* @return KraLayerTiles the geometry and decoded tiles.
* @throws IllegalArgumentException on an unexpected version, header, or a tile that fails to decode.
*/
internal fun parseKraLayerTiles(data: ByteArray): KraLayerTiles {
val cursor = AsciiLineCursor(data)
val version = headerValue(cursor.readLine(), "VERSION")
require(version == 2) {
"Unsupported KRA tile format version $version (expected 2)"
}
val tileWidth = headerValue(cursor.readLine(), "TILEWIDTH")
val tileHeight = headerValue(cursor.readLine(), "TILEHEIGHT")
val pixelSize = headerValue(cursor.readLine(), "PIXELSIZE")
val tileCount = headerValue(cursor.readLine(), "DATA")
val tileDataSize = pixelSize * tileWidth * tileHeight
val tiles = ArrayList<KraTile>(tileCount)
for (tileIndex in 0 until tileCount) {
// Tile header: x,y,LZF,dataSize. KRA: kis_tile_compressor_2.cpp:56-66.
val fields = cursor.readLine().split(',')
require(fields.size == 4) {
"Malformed KRA tile header at tile $tileIndex"
}
val left = fields[0].trim().toInt()
val top = fields[1].trim().toInt()
val compressionName = fields[2].trim()
val dataSize = fields[3].trim().toInt()
require(compressionName == "LZF") {
"Unsupported KRA tile compression '$compressionName' (expected LZF)"
}
val payloadOffset = cursor.position
val decoded = decodeTilePayload(data, payloadOffset, dataSize, tileDataSize, pixelSize)
cursor.skip(dataSize)
tiles.add(KraTile(left = left, top = top, pixels = decoded))
}
return KraLayerTiles(tileWidth = tileWidth, tileHeight = tileHeight, pixelSize = pixelSize, tiles = tiles)
}
/**
* Decodes one tile payload into interleaved native-order pixels.
*
* The first payload byte is the flag: KRA_RAW_DATA_FLAG means the remaining tileDataSize bytes are
* the pixels verbatim; KRA_COMPRESSED_DATA_FLAG means an LZF stream that inflates to a planar
* buffer, which is then de-interleaved with delinearizeColors.
*
* @param ByteArray data Buffer holding the tile payload.
* @param Int payloadOffset Offset of the flag byte.
* @param Int dataSize Total payload length (flag byte plus data).
* @param Int tileDataSize Expected decoded size (pixelSize * tileWidth * tileHeight).
* @param Int pixelSize Bytes per pixel (needed to de-interleave).
* @return ByteArray the decoded, interleaved tile pixels (tileDataSize bytes).
*/
private fun decodeTilePayload(
data: ByteArray,
payloadOffset: Int,
dataSize: Int,
tileDataSize: Int,
pixelSize: Int,
): ByteArray {
val flag = data[payloadOffset].toInt() and 0xFF
val packed = ByteArray(tileDataSize)
when (flag) {
KRA_RAW_DATA_FLAG -> {
// Already interleaved; copy the tileDataSize bytes after the flag.
data.copyInto(
packed,
destinationOffset = 0,
startIndex = payloadOffset + 1,
endIndex = payloadOffset + 1 + tileDataSize,
)
}
KRA_COMPRESSED_DATA_FLAG -> {
val planar = ByteArray(tileDataSize)
val written = lzfDecompress(data, payloadOffset + 1, dataSize - 1, planar)
require(written == tileDataSize) {
"KRA tile LZF decode produced $written bytes, expected $tileDataSize"
}
delinearizeColors(planar, packed, tileDataSize, pixelSize)
}
else -> error("Unknown KRA tile data flag $flag")
}
return packed
}
/**
* Parses a KEY value header line and returns the integer value, asserting the key matches.
*
* @param String line The header line (already newline-stripped).
* @param String expectedKey The key this line must start with.
* @return Int the parsed value.
*/
private fun headerValue(line: String, expectedKey: String): Int {
val parts = line.trim().split(' ', limit = 2)
require(parts.size == 2 && parts[0] == expectedKey) {
"Expected KRA tile header '$expectedKey <n>', got '$line'"
}
return parts[1].trim().toInt()
}
/**
* A tiny forward cursor that reads newline-terminated ASCII lines out of a mixed text/binary
* buffer, then hands off raw byte offsets for the binary tile payloads that follow each header line.
*
* @property ByteArray data The backing buffer.
*/
private class AsciiLineCursor(private val data: ByteArray) {
var position: Int = 0
private set
private val newline: Byte = '\n'.code.toByte()
/**
* Reads from the current position up to and consuming the next newline, returning the text.
*
* @return String the line without its trailing newline.
*/
fun readLine(): String {
val start = position
while (position < data.size && data[position] != newline) {
position++
}
val line = decodeAscii(data, start, position - start)
if (position < data.size) {
position++ // consume the newline
}
return line
}
/**
* Advances the cursor past count bytes of binary payload.
*
* @param Int count The number of bytes to skip.
*/
fun skip(count: Int) {
position += count
}
}
@@ -0,0 +1,170 @@
package org.umamo.format.moc3
import kotlinx.serialization.decodeFromString
import kotlinx.serialization.encodeToString
import org.umamo.format.FileKind
import org.umamo.format.FormatCodec
import org.umamo.format.FormatVersion
import org.umamo.format.moc3.decode.MocDecoder
import org.umamo.format.moc3.encode.MocEncoder
import org.umamo.format.moc3.json.Cdi3Json
import org.umamo.format.moc3.json.Model3Json
import org.umamo.format.moc3.json.Physics3Json
import org.umamo.format.moc3.json.SidecarJson
import org.umamo.format.moc3.json.UserData3Json
import org.umamo.format.moc3.moc.MocCodec
import org.umamo.format.moc3.moc.MocModel
import org.umamo.format.moc3.moc.MocVersion
/**
* Reads and writes Live2D Cubism runtime assets: the `.moc3` binary model and its JSON sidecars.
*
* Implements [FormatCodec] at the SEMANTIC tier: [read] decodes a file all the way to [MocDocument],
* and [write] synthesizes every section back from one, so read - edit - write is a real cycle here
* rather than a byte copy. Byte-exact container fidelity lives one layer down in [MocCodec], whose
* own read/write reproduce an unedited file byte-for-byte; reach that tier through [decode] and
* [bake] when the raw sections are what a caller needs. This is the same split CMO3 has, where the
* codec re-emits the model graph and CaffCodec holds the container bytes.
*
* The JSON sidecar helpers handle `model3.json` and friends. Those sidecars are `String`-shaped
* (not `ByteArray`), so they sit alongside the [FormatCodec] members rather than within them. The
* `.moc3` and its sidecars are sibling files (the manifest references the rest by path), so they are
* decoupled here - pair them yourself. Pure Kotlin (JVM + Android); no JDOM/reflection.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §8</a>
*/
public object Moc3 : FormatCodec<MocDocument> {
/** This codec handles [FileKind.Moc3]. */
override val kind: FileKind get() = FileKind.Moc3
/**
* True if [candidateBytes] starts with the `MOC3` magic and is at least header-sized.
*
* @param ByteArray candidateBytes Candidate file contents.
* @return Boolean Whether this looks like a `.moc3`.
*/
override fun matches(candidateBytes: ByteArray): Boolean = MocCodec.isMoc3(candidateBytes)
/**
* Cheap version probe: reads the version byte without parsing the section table.
*
* @param ByteArray bytes The complete file contents.
* @return FormatVersion? The `.moc3` version, or null when the magic or byte is unrecognized.
*/
override fun getVersion(bytes: ByteArray): FormatVersion? {
if (!MocCodec.isMoc3(bytes)) {
return null
}
// MOC3.md §version gating: version byte @ +0x04.
val versionByte = bytes[4].toInt() and 0xFF
return MocVersion.entries.firstOrNull { it.byteValue == versionByte }
}
/**
* Parses a `.moc3` and decodes it to the full semantic [MocDocument].
*
* @param ByteArray bytes The file contents.
* @return MocDocument The decoded document.
*/
override fun read(bytes: ByteArray): MocDocument = MocDecoder.decode(MocCodec.read(bytes))
/**
* Bakes [model] to runtime-valid `.moc3` bytes, synthesizing every section from the object model
* with no reference container involved.
*
* The output is runtime-valid, not byte-identical to whatever file the document was read from: the
* section layout is ours rather than the editor's. Go through [MocCodec] when a byte-exact re-emit
* of an unedited container is the point.
*
* @param MocDocument model The document to bake.
* @return ByteArray The complete `.moc3` file bytes.
*/
override fun write(model: MocDocument): ByteArray = MocEncoder.bakeFresh(model.version, model)
/**
* Decodes an already-parsed [MocModel] into the full semantic [MocDocument] - the container-tier
* entry, paired with [MocCodec.read] by a caller that wants the raw sections too.
*
* @param MocModel model The parsed model.
* @return MocDocument The decoded document.
*/
public fun decode(model: MocModel): MocDocument = MocDecoder.decode(model)
/**
* Bakes a (possibly-edited) [doc] onto [reference], synthesizing every section the lowering covers
* and carrying anything it does not from the reference container.
*
* That carry-through is empty for every corpus model (`MocBakeFreshCoverageTest` pins the carried
* set at nothing), so it stands against a section some later format version adds rather than against
* one we cannot derive. [write] is the reference-free form, and what an export uses.
*
* @param MocModel reference The decoded source providing the carried sections and the version.
* @param MocDocument doc The document to bake.
* @return ByteArray The baked `.moc3` file bytes.
*/
public fun bake(reference: MocModel, doc: MocDocument): ByteArray = MocEncoder.bake(reference, doc)
/**
* Parses a `model3.json` manifest.
*
* @param String text The file contents.
* @return Model3Json The parsed manifest.
*/
public fun readModel3(text: String): Model3Json = SidecarJson.decodeFromString(text)
/**
* Serializes a `model3.json` manifest (matches the editor's formatting).
*
* @param Model3Json model The manifest to write.
* @return String The serialized JSON.
*/
public fun writeModel3(model: Model3Json): String = SidecarJson.encodeToString(model)
/**
* Parses a `physics3.json` rig definition.
*
* @param String text The file contents.
* @return Physics3Json The parsed rig definition.
*/
public fun readPhysics3(text: String): Physics3Json = SidecarJson.decodeFromString(text)
/**
* Serializes a `physics3.json` rig definition.
*
* @param Physics3Json physics The rig definition to write.
* @return String The serialized JSON.
*/
public fun writePhysics3(physics: Physics3Json): String = SidecarJson.encodeToString(physics)
/**
* Parses a `cdi3.json` display-info file.
*
* @param String text The file contents.
* @return Cdi3Json The parsed display info.
*/
public fun readCdi3(text: String): Cdi3Json = SidecarJson.decodeFromString(text)
/**
* Serializes a `cdi3.json` display-info file.
*
* @param Cdi3Json displayInfo The display info to write.
* @return String The serialized JSON.
*/
public fun writeCdi3(displayInfo: Cdi3Json): String = SidecarJson.encodeToString(displayInfo)
/**
* Parses a `userdata3.json` file.
*
* @param String text The file contents.
* @return UserData3Json The parsed user data.
*/
public fun readUserData3(text: String): UserData3Json = SidecarJson.decodeFromString(text)
/**
* Serializes a `userdata3.json` file.
*
* @param UserData3Json userData The user data to write.
* @return String The serialized JSON.
*/
public fun writeUserData3(userData: UserData3Json): String = SidecarJson.encodeToString(userData)
}
@@ -0,0 +1,65 @@
package org.umamo.format.moc3
import org.umamo.format.moc3.moc.CanvasInfo
import org.umamo.format.moc3.moc.MocParameter
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.format.moc3.model.ArtMesh
import org.umamo.format.moc3.model.BlendShape
import org.umamo.format.moc3.model.Deformer
import org.umamo.format.moc3.model.Glue
import org.umamo.format.moc3.model.KeyformBinding
import org.umamo.format.moc3.model.Offscreen
import org.umamo.format.moc3.model.Part
import org.umamo.format.moc3.model.RenderOrderGroup
/**
* The fully decoded semantic model of a `.moc3` - the agnostic intermediate for editor
* reconstruction and (later) the bake.
*
* Objects reference each other and parameters by index (their position in these lists). Each
* deformable object names a `keyformBindingIndex`; look the binding up with [keyformBinding] to
* learn the controlling parameters and key positions for its keyforms. The per-frame
* interpolation/deformation math is intentionally not modelled - this is the stored data.
* Blend shapes (moc 4+) and offscreens (moc 6) are assembled into [blendShapes]/[offscreens];
* every section index is modeled in `Section`, though 149-151 (glue blend shapes)
* decode to nothing because no corpus sample carries one.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5</a>
*/
public class MocDocument(
public val version: MocVersion,
public val canvas: CanvasInfo?,
public val parameters: List<MocParameter>,
private val keyformBindings: Map<Int, KeyformBinding>,
public val parts: List<Part>,
public val deformers: List<Deformer>,
public val artMeshes: List<ArtMesh>,
public val glues: List<Glue>,
public val renderOrderGroups: List<RenderOrderGroup>,
/** Blend-shape records (moc 4+); empty on older versions. */
public val blendShapes: List<BlendShape> = emptyList(),
/** Offscreen render targets (moc 6); empty on older versions. */
public val offscreens: List<Offscreen> = emptyList(),
/**
* Whether a blend-free file's KEY_POSITIONS (section 77) carries the trailing per-parameter
* sorted-union key region. This is an editor-version artifact: some Cubism editor builds append
* the union of each parameter's main-grid axis keys after the parameter-binding dedup region,
* others omit it, and no other section or header field distinguishes the two (probed across the
* v1/v3 corpus - the section tables and headers are byte-identical). Carried so the lowering can
* reproduce section 77 byte-exact; the runtime recomputes the same unions when the region is
* absent (a model with multi-keyset parameters loads correctly either way). A blend model always
* carries the region unconditionally, so this flag only disambiguates the blend-free path.
*/
public val keyPositionsHasParameterUnion: Boolean = false,
) {
/** All resolved keyform bindings referenced by objects, ascending by index. */
public val bindings: List<KeyformBinding> get() = keyformBindings.values.sortedBy { it.index }
/**
* The keyform binding with the given index, or null if no object references it.
*
* @param Int index A `keyformBindingIndex` from an object.
* @return KeyformBinding? The resolved binding.
*/
public fun keyformBinding(index: Int): KeyformBinding? = keyformBindings[index]
}
@@ -0,0 +1,126 @@
package org.umamo.format.moc3.decode
import org.umamo.format.moc3.moc.MocDrawable
import org.umamo.format.moc3.moc.MocSections
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.model.ArtMesh
import org.umamo.format.moc3.model.ArtMeshKeyform
/**
* Decodes the drawables into [ArtMesh]es: their geometry slices and per-keyform values.
*
* A drawable's UVs, triangle indices, and mask indices are not addressed by any index table -
* they are CONCATENATED per drawable in drawable order, so the decode carries a running cursor
* per table and advances it by that drawable's own counts. The mask cursor is the one that does
* not start at zero: the offscreen mask entries are the block's prefix (MOC3 v6 §5.6 section 80).
*/
internal class MocArtMeshDecoder(
sections: MocSections,
private val bindings: MocBindingResolver,
private val colorTables: ColorTables,
private val keyformValues: KeyformValueTables,
private val maskData: IntArray,
) {
private val keyformBindingIndex = sections.intArray(Section.ARTMESH_KEYFORM_BINDING)
private val keyformBase = sections.intArray(Section.ARTMESH_KEYFORM_BASE)
private val parentDeformer = sections.intArray(Section.ARTMESH_PARENT_DEFORMER)
private val colorBase =
if (sections.isPresent(Section.ARTMESH_COLOR_BASE)) sections.intArray(Section.ARTMESH_COLOR_BASE) else null
// MOC3 v6 §5.6 s153: per-drawable packed extended blend (0 = legacy constant-flags blend).
private val extendedBlend =
if (sections.isPresent(Section.ARTMESH_EXTENDED_BLEND)) sections.intArray(Section.ARTMESH_EXTENDED_BLEND) else null
// s37 is the visibility toggle (pinned by joining miku_verycursed against its CMO3 twin); s38 is
// 1 on every drawable of every corpus sample and is carried only so a bake reproduces it.
private val isVisible = sections.intArray(Section.ARTMESH_IS_VISIBLE)
private val isEnabled = sections.intArray(Section.ARTMESH_IS_ENABLED)
private val uvData = sections.floatArray(Section.ARTMESH_UV_DATA)
private val indexData = sections.shortArray(Section.ARTMESH_INDEX_DATA)
/**
* Where the drawables' mask entries begin: the offscreen entries are the block's PREFIX and
* the drawables' masks follow (pinned on Model A against the CMO3 ground truth + the runtime's
* s158 addressing, which offsets from the block start). Pre-v6 there is no prefix.
*/
private val offscreenMaskTotal =
if (sections.isPresent(Section.OFFSCREEN_MASK_COUNT)) {
sections.intArray(Section.OFFSCREEN_MASK_COUNT).sum()
} else {
0
}
/**
* Decodes every drawable, walking the concatenated geometry tables in drawable order.
*
* @param List<MocDrawable> drawables The model's drawables, whose counts drive the cursors.
* @return List<ArtMesh> The decoded art meshes, in drawable order.
*/
fun decodeAll(drawables: List<MocDrawable>): List<ArtMesh> {
var vertexBase = 0
var indexBase = 0
var maskBase = offscreenMaskTotal
return drawables.mapIndexed { drawableIndex, drawable ->
val vertexCount = drawable.vertexCount
val uvs = uvData.copyOfRange(vertexBase * 2, vertexBase * 2 + vertexCount * 2)
val triangleIndices = indexData.copyOfRange(indexBase, indexBase + drawable.indexCount)
val maskIndices = maskData.copyOfRange(maskBase, maskBase + drawable.maskCount)
vertexBase += vertexCount
indexBase += drawable.indexCount
maskBase += drawable.maskCount
artMesh(drawableIndex, drawable, uvs, triangleIndices, maskIndices)
}
}
/**
* Builds one art mesh from its already-sliced geometry plus its per-keyform values.
*
* @param Int drawableIndex The drawable's index (every per-drawable table's row).
* @param MocDrawable drawable The drawable header (id, texture, flags, counts).
* @param FloatArray uvs This drawable's slice of the UV table.
* @param ShortArray triangleIndices This drawable's slice of the index table.
* @param IntArray maskIndices This drawable's slice of the mask table.
* @return ArtMesh The decoded art mesh.
*/
private fun artMesh(
drawableIndex: Int,
drawable: MocDrawable,
uvs: FloatArray,
triangleIndices: ShortArray,
maskIndices: IntArray,
): ArtMesh {
val keyformBinding = keyformBindingIndex[drawableIndex]
val base = keyformBase[drawableIndex]
val keyforms =
(0 until bindings.binding(keyformBinding).gridSize).map { gridIndex ->
val positionOffset = keyformValues.positionIndex[base + gridIndex]
ArtMeshKeyform(
keyformValues.positionValues.copyOfRange(
positionOffset,
positionOffset + drawable.vertexCount * 2,
),
keyformValues.artMeshOpacity[base + gridIndex],
keyformValues.artMeshDrawOrder[base + gridIndex],
colorTables.multiplyForKeyform(colorBase?.get(drawableIndex), gridIndex),
colorTables.screenForKeyform(colorBase?.get(drawableIndex), gridIndex),
)
}
return ArtMesh(
drawable.id,
drawable.textureIndex,
drawable.constantFlags,
extendedBlend?.get(drawableIndex) ?: 0,
// Default to visible: a stripped file omitting the flags means "nothing is hidden".
isVisible.getOrElse(drawableIndex) { 1 } != 0,
isEnabled.getOrElse(drawableIndex) { 1 } != 0,
drawable.parentPartIndex,
parentDeformer[drawableIndex],
uvs,
triangleIndices,
maskIndices,
keyformBinding,
keyforms,
)
}
}
@@ -0,0 +1,128 @@
package org.umamo.format.moc3.decode
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.moc.MocSections
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.model.KeyformAxis
import org.umamo.format.moc3.model.KeyformBinding
/**
* Resolves keyform-binding indices into [KeyformBinding]s, and accumulates every one it resolves.
*
* This is deliberately an accumulator, not merely a cache: the set it has resolved BECOMES
* [MocDocument.keyformBindings], so registering a binding is how it reaches the document. Callers
* therefore resolve through [binding] even when they only want the grid size, and the glue pass
* resolves bindings purely to register them. Call [collected] and [hasParameterUnionRegion] only
* after every object kind has been decoded, or the tail of the binding table goes missing.
*/
internal class MocBindingResolver(sections: MocSections) {
/**
* Owning parameter per binding slot, expanded from the per-parameter slot counts (MOC3 §5.6
* section 57): the slot table is a flat concatenation, so the parameter is positional.
*/
private val owningParameter: IntArray
private val keyOffset: IntArray = sections.intArray(Section.BINDING_KEY_OFFSET)
private val keyCount: IntArray = sections.intArray(Section.BINDING_KEY_COUNT)
private val keyformBindingSlot: IntArray = sections.intArray(Section.KEYFORM_BINDING_SLOT)
private val keyformBindingStart: IntArray = sections.intArray(Section.KEYFORM_BINDING_START)
private val keyformBindingCount: IntArray = sections.intArray(Section.KEYFORM_BINDING_COUNT)
private val resolved = HashMap<Int, KeyformBinding>()
/** The shared key-position table (MOC3 §5.6 section 77); the blend path reads it too. */
val keyPositions: FloatArray = sections.floatArray(Section.KEY_POSITIONS)
init {
val bindingCountPerParameter = sections.intArray(Section.PARAMETER_BINDING_COUNT)
owningParameter = IntArray(bindingCountPerParameter.sum())
var bindingSlot = 0
for (parameterIndex in bindingCountPerParameter.indices) {
repeat(bindingCountPerParameter[parameterIndex]) { owningParameter[bindingSlot++] = parameterIndex }
}
}
/** Every binding resolved so far, which is what the document carries. */
val collected: Map<Int, KeyformBinding> get() = resolved.toMap()
/**
* Resolves the keyform binding at [keyformBindingIndex] into its parameter axes, registering it.
*
* @param Int keyformBindingIndex A keyform-binding index referenced by an object.
* @return KeyformBinding The resolved binding (its controlling parameter axes + key positions).
*/
fun binding(keyformBindingIndex: Int): KeyformBinding =
resolved.getOrPut(keyformBindingIndex) {
val start = keyformBindingStart[keyformBindingIndex]
val axes =
(0 until keyformBindingCount[keyformBindingIndex]).map { axisIndex ->
val bindingSlot = keyformBindingSlot[start + axisIndex]
KeyformAxis(
owningParameter[bindingSlot],
keyPositions.copyOfRange(
keyOffset[bindingSlot],
keyOffset[bindingSlot] + keyCount[bindingSlot],
),
)
}
KeyformBinding(keyformBindingIndex, axes)
}
/**
* The grid size of a binding, treating a part's 0 as "static" rather than as binding 0.
*
* @param Int keyformBindingIndex A part's keyform-binding index, where 0 means no binding.
* @return Int The keyform grid size, 1 when static.
*/
fun staticAwareGridSize(keyformBindingIndex: Int): Int =
if (keyformBindingIndex <= 0) {
1
} else {
binding(keyformBindingIndex).gridSize
}
/**
* Registers every binding record the file stores, not only those objects reference.
*
* The file allocates CountInfo[12] records, and a mesh-less model carries a single EMPTY
* binding (0 axes) that only static parts point at - lazy by-reference registration would drop
* it and shrink the re-synthesized binding sections + CountInfo (probed on the
* ModelWithOffscreen family). MOC3 §5.1 CountInfo field 12.
*
* @param Int storedBindingCount The stored record count, CountInfo field 12.
*/
fun registerStoredBindings(storedBindingCount: Int) {
repeat(storedBindingCount) { bindingIndex ->
binding(bindingIndex)
}
}
/**
* Total keys the deduplicated main-grid region of KEY_POSITIONS holds, over the bindings
* registered so far. This is where the optional trailing union region begins.
*
* @return Int The main-grid key total.
*/
private fun mainGridKeyTotal(): Int {
val keySetsByParameter = HashMap<Int, LinkedHashSet<List<Float>>>()
for (resolvedBinding in resolved.values) {
for (axis in resolvedBinding.axes) {
keySetsByParameter.getOrPut(axis.parameterIndex) { LinkedHashSet() }.add(axis.keyPositions.toList())
}
}
return keySetsByParameter.values.sumOf { keySets -> keySets.sumOf { it.size } }
}
/**
* Whether KEY_POSITIONS (77) trails its dedup region with the per-parameter sorted-union of the
* main-grid axis keys, an editor-version artifact on some blend-free v1/v3 files (MOC3 §5.6).
*
* Detected as any nonzero key beyond the dedup (main-grid) region; zero padding beyond the
* region reads as absent. Only meaningful on a blend-free file - a blend model carries the
* region unconditionally, which the blend lowering path handles.
*
* @param Boolean isBlendFree Whether the model decoded no blend shapes.
* @return Boolean Whether the trailing union region is present.
*/
fun hasParameterUnionRegion(isBlendFree: Boolean): Boolean =
isBlendFree && (mainGridKeyTotal() until keyPositions.size).any { keyIndex -> keyPositions[keyIndex] != 0f }
}
@@ -0,0 +1,504 @@
package org.umamo.format.moc3.decode
import org.umamo.format.moc3.moc.MocSections
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.model.ArtMeshKeyform
import org.umamo.format.moc3.model.BlendShape
import org.umamo.format.moc3.model.BlendShapeKeyform
import org.umamo.format.moc3.model.BlendShapeLimit
import org.umamo.format.moc3.model.BlendShapeTarget
import org.umamo.format.moc3.model.Part
import org.umamo.format.moc3.model.Rgb
import org.umamo.format.moc3.model.RotationKeyform
import org.umamo.format.moc3.model.WarpKeyform
/**
* The per-object payload sizes and row anchor a blend-shape record's delta rows need, over the
* shared [KeyformValueTables]. Bundled so [BlendShapeDecoder] can lift the per-key delta payloads
* without a dozen loose parameters.
*/
internal class BlendDeltaTables(
val keyformValues: KeyformValueTables,
val colorTables: ColorTables,
val warpControlPointCounts: IntArray,
val drawableVertexCounts: IntArray,
/**
* First color-table row of the blend delta region: the moc-6 offscreen keyform prefix plus
* every object's base keyform rows. Computed from CONTENT, not from the table length - the
* raw element region is 64-byte zero-padded, so length-based anchoring drifts by the pad.
*/
val colorDeltaRowStart: Int,
)
/**
* The deduplicated blend-weight limit pool (MOC3 v4+ §5.6 sections 123/124 + 131-136).
*
* A record ranges into SUB_INDEX, whose entries name a shared pool of (parameter, keys, weights)
* curves; records commonly point at the same pool entry, so the pool is stored once and expanded
* per record here. Absent tables decode as no limits, like any absent section.
*/
internal class BlendLimitPool(sections: MocSections) {
private val recordSubstart = sections.intArray(Section.BLENDSHAPE_RECORD_SUBSTART)
private val recordCornerCount = sections.intArray(Section.BLENDSHAPE_RECORD_CORNER_COUNT)
private val hasSubTables = sections.isPresent(Section.BLENDSHAPE_SUB_INDEX)
private val subIndex = if (hasSubTables) sections.intArray(Section.BLENDSHAPE_SUB_INDEX) else IntArray(0)
private val subParameter = if (hasSubTables) sections.intArray(Section.BLENDSHAPE_SUB_PARAMETER) else IntArray(0)
private val subKeyOffset = if (hasSubTables) sections.intArray(Section.BLENDSHAPE_SUB_KEY_OFFSET) else IntArray(0)
private val subKeyCount = if (hasSubTables) sections.intArray(Section.BLENDSHAPE_SUB_KEY_COUNT) else IntArray(0)
private val subKeys = if (hasSubTables) sections.floatArray(Section.BLENDSHAPE_SUB_KEYS) else FloatArray(0)
private val subWeights = if (hasSubTables) sections.floatArray(Section.BLENDSHAPE_SUB_WEIGHT_VALUES) else FloatArray(0)
/**
* Expands one record's sub-binding refs into its limit curves (empty when uncapped).
*
* @param Int recordIndex The record's index in the record tables.
* @return List<BlendShapeLimit> The record's limits, pool entries expanded per record.
*/
fun limitsFor(recordIndex: Int): List<BlendShapeLimit> {
if (!hasSubTables || recordIndex >= recordCornerCount.size) {
return emptyList()
}
val cornerCount = recordCornerCount[recordIndex]
if (cornerCount == 0) {
return emptyList()
}
val cornerStart = recordSubstart[recordIndex]
return (cornerStart until cornerStart + cornerCount).map { cornerIndex ->
val subBinding = subIndex[cornerIndex]
val keyOffset = subKeyOffset[subBinding]
val keyCount = subKeyCount[subBinding]
BlendShapeLimit(
parameterIndex = subParameter[subBinding],
keyPositions = subKeys.copyOfRange(keyOffset, keyOffset + keyCount),
weights = subWeights.copyOfRange(keyOffset, keyOffset + keyCount),
)
}
}
}
/**
* Per-record addressing into the color tables' blend-delta region (MOC3 §5.6 sections 108-113).
*
* The delta region follows the base rows (and, on MOC3 v6, the offscreen keyform prefix), holding
* one row per (record, key) for warp, mesh, and rotation records in global record order - part
* records own no color rows. It anchors at the content-derived base-row total
* ([BlendDeltaTables.colorDeltaRowStart]); anchoring at table length minus the delta total drifts
* by the element region's 64-byte zero padding (2 rows on Model A, 10 on Model C - caught by
* their authored color morphs).
*
* The region is also a later format addition, so presence is probed rather than assumed: a
* 4.2-era bake with blend shapes carries the base rows only (corpus: Azxiana.moc3, V42 - CountInfo
* 23/24 there count base + prefix rows while fields 7-9 still include the deltas). When the
* tables do not cover the read extent, every record resolves to the absent sentinel and the deltas
* decode as null colors.
*/
internal class BlendColorDeltas(
sections: MocSections,
recordCount: Int,
recordBinding: IntArray,
bindingKeyCount: IntArray,
deltaTables: BlendDeltaTables,
) {
private val colorTables: ColorTables = deltaTables.colorTables
/** Each record's first delta row, or -1 when it owns none (part-owned, or the region absent). */
private val recordColorRow: IntArray
init {
val partOwnedRecord = partOwnedRecords(sections, recordCount)
val colorReadRecord = colorReadRecords(sections, recordCount)
// Measure the read extent over exactly the rows that will be dereferenced: the record
// tables carry a few TRAILING records referenced by no group on every blend corpus model,
// and the stored region ends at the referenced records' rows (modelA: table 1808 = read
// extent 1806 + 2 rows padding; modelC: 2208 = 2198 + 10).
var requiredRowEnd = deltaTables.colorDeltaRowStart
var rowProbeCursor = deltaTables.colorDeltaRowStart
for (recordIndex in 0 until recordCount) {
if (!partOwnedRecord[recordIndex]) {
val rowEnd = rowProbeCursor + bindingKeyCount[recordBinding[recordIndex]]
if (colorReadRecord[recordIndex] && rowEnd > requiredRowEnd) {
requiredRowEnd = rowEnd
}
rowProbeCursor = rowEnd
}
}
val rows = IntArray(recordCount) { -1 }
if (colorTables.isPresent && requiredRowEnd <= colorTables.rowCount) {
var colorRowCursor = deltaTables.colorDeltaRowStart
for (recordIndex in 0 until recordCount) {
if (!partOwnedRecord[recordIndex]) {
rows[recordIndex] = colorRowCursor
colorRowCursor += bindingKeyCount[recordBinding[recordIndex]]
}
}
}
recordColorRow = rows
}
/**
* Marks the records owned by a part object group, which carry no color rows.
*
* @param MocSections sections The model's typed sections.
* @param Int recordCount Total blend-shape records.
* @return BooleanArray One flag per record.
*/
private fun partOwnedRecords(sections: MocSections, recordCount: Int): BooleanArray {
val owned = BooleanArray(recordCount)
if (!sections.isPresent(Section.BLENDSHAPE_PART_OBJECT)) {
return owned
}
val partRecordStarts = sections.intArray(Section.BLENDSHAPE_PART_RECORD_START)
val partRecordCounts = sections.intArray(Section.BLENDSHAPE_PART_RECORD_COUNT)
for (groupIndex in partRecordStarts.indices) {
val partRecordEnd = partRecordStarts[groupIndex] + partRecordCounts[groupIndex]
for (recordIndex in partRecordStarts[groupIndex] until partRecordEnd) {
owned[recordIndex] = true
}
}
return owned
}
/**
* Marks the records a warp, mesh, or rotation object group references - the only ones whose
* color rows are ever dereferenced.
*
* @param MocSections sections The model's typed sections.
* @param Int recordCount Total blend-shape records.
* @return BooleanArray One flag per record.
*/
private fun colorReadRecords(sections: MocSections, recordCount: Int): BooleanArray {
val referenced = BooleanArray(recordCount)
val groups =
listOf(
Triple(
Section.BLENDSHAPE_WARP_OBJECT,
Section.BLENDSHAPE_WARP_RECORD_START,
Section.BLENDSHAPE_WARP_RECORD_COUNT,
),
Triple(
Section.BLENDSHAPE_MESH_OBJECT,
Section.BLENDSHAPE_MESH_RECORD_START,
Section.BLENDSHAPE_MESH_RECORD_COUNT,
),
Triple(
Section.BLENDSHAPE_ROTATION_OBJECT,
Section.BLENDSHAPE_ROTATION_RECORD_START,
Section.BLENDSHAPE_ROTATION_RECORD_COUNT,
),
)
for ((objectSection, startSection, countSection) in groups) {
if (!sections.isPresent(objectSection)) {
continue
}
val recordStarts = sections.intArray(startSection)
val recordCounts = sections.intArray(countSection)
for (groupIndex in recordStarts.indices) {
for (recordIndex in recordStarts[groupIndex] until recordStarts[groupIndex] + recordCounts[groupIndex]) {
if (recordIndex in 0 until recordCount) {
referenced[recordIndex] = true
}
}
}
}
return referenced
}
/**
* Multiply-color delta at key [keyIndex] of record [recordIndex].
*
* @param Int recordIndex The record's index in the record tables.
* @param Int keyIndex The key's index within the record's binding.
* @return Rgb? The multiply-color delta row, or null when the record owns no color rows.
*/
fun multiplyDelta(recordIndex: Int, keyIndex: Int): Rgb? {
val colorRow = recordColorRow[recordIndex]
// Guarded here rather than folded into the row accessor: a negative row is the "no delta
// rows" sentinel, and offsetting it by keyIndex would land on a real row.
return if (colorRow < 0) {
null
} else {
colorTables.multiplyAtRow(colorRow + keyIndex)
}
}
/**
* Screen-color delta at key [keyIndex] of record [recordIndex].
*
* @param Int recordIndex The record's index in the record tables.
* @param Int keyIndex The key's index within the record's binding.
* @return Rgb? The screen-color delta row, or null when the record owns no color rows.
*/
fun screenDelta(recordIndex: Int, keyIndex: Int): Rgb? {
val colorRow = recordColorRow[recordIndex]
// Same sentinel guard as multiplyDelta above.
return if (colorRow < 0) {
null
} else {
colorTables.screenAtRow(colorRow + keyIndex)
}
}
}
/**
* Decodes the blend-shape records: the binding structure, each record's blend-weight limits, and
* the typed per-key delta payloads.
*
* The records live in one flat table addressed by per-kind object groups (MOC3 v4+ §5.6 for
* meshes/warps, v5+ for rotations and parts). A group names its objects by KIND-LOCAL index,
* which is what sizes a delta payload, while the emitted [BlendShape] carries the deformer or
* drawable index instead - hence both travel together through the decode.
*/
internal class BlendShapeDecoder(
private val sections: MocSections,
parameterCount: Int,
private val keyPositions: FloatArray,
private val deltaTables: BlendDeltaTables,
) {
private val bindingKeyOffset = sections.intArray(Section.BLENDSHAPE_BINDING_KEY_OFFSET)
private val bindingKeyCount = sections.intArray(Section.BLENDSHAPE_BINDING_KEY_COUNT)
private val bindingNeutral = sections.intArray(Section.BLENDSHAPE_BINDING_NEUTRAL)
private val recordBinding = sections.intArray(Section.BLENDSHAPE_RECORD_BINDING)
private val recordBase = sections.intArray(Section.BLENDSHAPE_RECORD_BASE)
private val bindingOwner = resolveBindingOwners(sections, parameterCount)
private val limitPool = BlendLimitPool(sections)
private val colorDeltas =
BlendColorDeltas(sections, recordBinding.size, recordBinding, bindingKeyCount, deltaTables)
/** The shared value tables the delta rows live in; aliased to keep the payload reads legible. */
private val keyformValues = deltaTables.keyformValues
/**
* Resolves the owning parameter of every blend-shape binding.
*
* Unlike the main keyform bindings, whose slot table is a flat concatenation, these carry
* explicit begin/count ranges per parameter (MOC3 §5.6).
*
* @param MocSections sections The model's typed sections.
* @param Int parameterCount Number of parameters.
* @return IntArray The owning parameter index per binding.
*/
private fun resolveBindingOwners(sections: MocSections, parameterCount: Int): IntArray {
val parameterBegin = sections.intArray(Section.BLENDSHAPE_PARAMETER_BEGIN)
val parameterBindingCount = sections.intArray(Section.BLENDSHAPE_PARAMETER_COUNT)
val owners = IntArray((0 until parameterCount).sumOf { parameterBindingCount[it] })
for (parameterIndex in 0 until parameterCount) {
for (bindingIndex in 0 until parameterBindingCount[parameterIndex]) {
owners[parameterBegin[parameterIndex] + bindingIndex] = parameterIndex
}
}
return owners
}
/**
* Decodes every object group's records, in warp, mesh, rotation, then part order.
*
* @param List<Int> warpToDeformer Maps a warp local index to its deformer index.
* @param List<Int> rotationToDeformer Maps a rotation local index to its deformer index.
* @return List<BlendShape> The decoded records.
*/
fun decodeAll(warpToDeformer: List<Int>, rotationToDeformer: List<Int>): List<BlendShape> {
val blendShapes = ArrayList<BlendShape>()
blendShapes +=
groupRecords(
Section.BLENDSHAPE_WARP_OBJECT,
Section.BLENDSHAPE_WARP_RECORD_START,
Section.BLENDSHAPE_WARP_RECORD_COUNT,
BlendShapeTarget.WARP,
warpToDeformer,
)
blendShapes +=
groupRecords(
Section.BLENDSHAPE_MESH_OBJECT,
Section.BLENDSHAPE_MESH_RECORD_START,
Section.BLENDSHAPE_MESH_RECORD_COUNT,
BlendShapeTarget.ART_MESH,
null,
)
blendShapes +=
groupRecords(
Section.BLENDSHAPE_ROTATION_OBJECT,
Section.BLENDSHAPE_ROTATION_RECORD_START,
Section.BLENDSHAPE_ROTATION_RECORD_COUNT,
BlendShapeTarget.ROTATION,
rotationToDeformer,
)
// MOC3 v5+ §5.6 sections 143-145: part blend shapes (the object index is a part index).
blendShapes +=
groupRecords(
Section.BLENDSHAPE_PART_OBJECT,
Section.BLENDSHAPE_PART_RECORD_START,
Section.BLENDSHAPE_PART_RECORD_COUNT,
BlendShapeTarget.PART,
null,
)
return blendShapes
}
/**
* Decodes the records of one target kind's object group.
*
* @param Section objectSection The per-object index section for this group.
* @param Section startSection The per-object record-start section.
* @param Section countSection The per-object record-count section.
* @param BlendShapeTarget target The target kind these records deform.
* @param List<Int>? toDeformer Local-index to deformer-index map, or null when the
* object index already names the target directly.
* @return List<BlendShape> This group's records (empty when the section is absent).
*/
private fun groupRecords(
objectSection: Section,
startSection: Section,
countSection: Section,
target: BlendShapeTarget,
toDeformer: List<Int>?,
): List<BlendShape> {
if (!sections.isPresent(objectSection)) {
return emptyList()
}
val objectIndices = sections.intArray(objectSection)
val recordStarts = sections.intArray(startSection)
val recordCounts = sections.intArray(countSection)
val groupShapes = ArrayList<BlendShape>()
for (groupIndex in objectIndices.indices) {
val localObjectIndex = objectIndices[groupIndex]
val objectIndex = toDeformer?.getOrElse(localObjectIndex) { localObjectIndex } ?: localObjectIndex
val recordStart = recordStarts[groupIndex]
for (recordIndex in recordStart until recordStart + recordCounts[groupIndex]) {
groupShapes.add(blendShape(target, localObjectIndex, objectIndex, recordIndex))
}
}
return groupShapes
}
/**
* Builds one record's [BlendShape], resolving its binding and lifting its delta payloads.
*
* @param BlendShapeTarget target Which kind of object this record deforms.
* @param Int localObjectIndex The target's kind-local index (sizes the payloads).
* @param Int objectIndex The deformer/drawable/part index the record targets.
* @param Int recordIndex The record's index in the record tables.
* @return BlendShape The decoded record.
*/
private fun blendShape(
target: BlendShapeTarget,
localObjectIndex: Int,
objectIndex: Int,
recordIndex: Int,
): BlendShape {
val bindingIndex = recordBinding[recordIndex]
val keys =
keyPositions.copyOfRange(
bindingKeyOffset[bindingIndex],
bindingKeyOffset[bindingIndex] + bindingKeyCount[bindingIndex],
)
return BlendShape(
target,
objectIndex,
bindingOwner[bindingIndex],
keys,
bindingNeutral[bindingIndex],
recordBase[recordIndex],
limitPool.limitsFor(recordIndex),
keyformsFor(target, localObjectIndex, recordIndex, bindingKeyCount[bindingIndex]),
)
}
/**
* Lifts one record's per-key delta payloads out of the shared value tables, at rows
* `recordBase + keyIndex` (MOC3 §5.6; the same tables the base keyforms use).
*
* @param BlendShapeTarget target The record's target kind.
* @param Int localObjectIndex The target's kind-local index (warp/rotation local,
* drawable, or part index) - sizes the payload.
* @param Int recordIndex The record's index in the record tables.
* @param Int keyCount The record's binding key count.
* @return List<BlendShapeKeyform> One delta payload per key, kind matching [target].
*/
private fun keyformsFor(
target: BlendShapeTarget,
localObjectIndex: Int,
recordIndex: Int,
keyCount: Int,
): List<BlendShapeKeyform> =
(0 until keyCount).map { keyIndex ->
val deltaRow = recordBase[recordIndex] + keyIndex
when (target) {
BlendShapeTarget.WARP -> warpDelta(localObjectIndex, recordIndex, keyIndex, deltaRow)
BlendShapeTarget.ART_MESH -> meshDelta(localObjectIndex, recordIndex, keyIndex, deltaRow)
BlendShapeTarget.ROTATION -> rotationDelta(recordIndex, keyIndex, deltaRow)
// MOC3 §5.6: part delta rows are draw-order floats in section 58.
BlendShapeTarget.PART -> BlendShapeKeyform.Part(keyformValues.partDrawOrder[deltaRow])
}
}
/**
* One warp control-point delta payload.
*
* @param Int localObjectIndex The warp's local index, which sizes the lattice.
* @param Int recordIndex The record's index in the record tables.
* @param Int keyIndex The key's index within the record's binding.
* @param Int deltaRow The record's row for this key.
* @return BlendShapeKeyform.Warp The delta payload.
*/
private fun warpDelta(localObjectIndex: Int, recordIndex: Int, keyIndex: Int, deltaRow: Int): BlendShapeKeyform.Warp {
// MOC3 §5.6: warp delta rows index packed position blocks via section 60 into 71.
val controlPointCount = deltaTables.warpControlPointCounts[localObjectIndex]
val positionOffset = keyformValues.warpPositionIndex[deltaRow]
return BlendShapeKeyform.Warp(
WarpKeyform(
keyformValues.positionValues.copyOfRange(positionOffset, positionOffset + controlPointCount * 2),
keyformValues.warpOpacity[deltaRow],
colorDeltas.multiplyDelta(recordIndex, keyIndex),
colorDeltas.screenDelta(recordIndex, keyIndex),
),
)
}
/**
* One art-mesh vertex delta payload.
*
* @param Int localObjectIndex The drawable index, which sizes the vertex block.
* @param Int recordIndex The record's index in the record tables.
* @param Int keyIndex The key's index within the record's binding.
* @param Int deltaRow The record's row for this key.
* @return BlendShapeKeyform.Mesh The delta payload.
*/
private fun meshDelta(localObjectIndex: Int, recordIndex: Int, keyIndex: Int, deltaRow: Int): BlendShapeKeyform.Mesh {
// MOC3 §5.6: mesh delta rows index packed position blocks via section 70 into 71.
val vertexCount = deltaTables.drawableVertexCounts[localObjectIndex]
val positionOffset = keyformValues.positionIndex[deltaRow]
return BlendShapeKeyform.Mesh(
ArtMeshKeyform(
keyformValues.positionValues.copyOfRange(positionOffset, positionOffset + vertexCount * 2),
keyformValues.artMeshOpacity[deltaRow],
keyformValues.artMeshDrawOrder[deltaRow],
colorDeltas.multiplyDelta(recordIndex, keyIndex),
colorDeltas.screenDelta(recordIndex, keyIndex),
),
)
}
/**
* One rotation affine delta payload.
*
* @param Int recordIndex The record's index in the record tables.
* @param Int keyIndex The key's index within the record's binding.
* @param Int deltaRow The record's row for this key.
* @return BlendShapeKeyform.Rotation The delta payload.
*/
private fun rotationDelta(recordIndex: Int, keyIndex: Int, deltaRow: Int): BlendShapeKeyform.Rotation =
// MOC3 §5.6: rotation delta rows sit directly in the affine tables 61-67.
BlendShapeKeyform.Rotation(
RotationKeyform(
keyformValues.rotationOriginX[deltaRow],
keyformValues.rotationOriginY[deltaRow],
keyformValues.rotationAngle[deltaRow],
keyformValues.rotationScale[deltaRow],
keyformValues.rotationReflectX[deltaRow] != 0,
keyformValues.rotationReflectY[deltaRow] != 0,
keyformValues.rotationOpacity[deltaRow],
colorDeltas.multiplyDelta(recordIndex, keyIndex),
colorDeltas.screenDelta(recordIndex, keyIndex),
),
)
}
@@ -0,0 +1,143 @@
package org.umamo.format.moc3.decode
import org.umamo.format.moc3.moc.MocSections
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.model.Rgb
/**
* The shared per-keyform color tables (MOC3 §5.6 sections 108-113) and their row addressing.
*
* Every consumer reaches the same six tables by a different route - a base keyform as
* `colorBase + gridIndex`, an offscreen as one of the block's prefix rows, a blend-shape delta as
* a delta row - so the addressing is expressed once as [multiplyAtRow] / [screenAtRow] and the
* keyform form layers on top. An absent color section yields a null color from every accessor,
* which is what keeps the presence check off the call sites.
*/
internal class ColorTables(sections: MocSections) {
/** Whether the model carries color tables at all; absent on a model with no color animation. */
val isPresent: Boolean = sections.isPresent(Section.COLOR_MULTIPLY_R)
private val multiplyR: FloatArray = sections.floatArray(Section.COLOR_MULTIPLY_R)
private val multiplyG: FloatArray = sections.floatArray(Section.COLOR_MULTIPLY_G)
private val multiplyB: FloatArray = sections.floatArray(Section.COLOR_MULTIPLY_B)
private val screenR: FloatArray = sections.floatArray(Section.COLOR_SCREEN_R)
private val screenG: FloatArray = sections.floatArray(Section.COLOR_SCREEN_G)
private val screenB: FloatArray = sections.floatArray(Section.COLOR_SCREEN_B)
/**
* Rows the tables hold, which the blend path probes against to decide whether the delta region
* was baked at all (a 4.2-era bake carries the base rows only).
*/
val rowCount: Int get() = multiplyR.size
/**
* Multiply-color at absolute table row [row].
*
* @param Int row The absolute row index; negative means "this object has no color row".
* @return Rgb? The multiply color, or null when the tables are absent or [row] is negative.
*/
fun multiplyAtRow(row: Int): Rgb? =
if (isPresent && row >= 0) {
Rgb(multiplyR[row], multiplyG[row], multiplyB[row])
} else {
null
}
/**
* Screen-color at absolute table row [row].
*
* @param Int row The absolute row index; negative means "this object has no color row".
* @return Rgb? The screen color, or null when the tables are absent or [row] is negative.
*/
fun screenAtRow(row: Int): Rgb? =
if (isPresent && row >= 0) {
Rgb(screenR[row], screenG[row], screenB[row])
} else {
null
}
/**
* Multiply-color at keyform [gridIndex] of an object whose color table starts at [colorBase].
*
* @param Int? colorBase The object's base row (null or -1 when the object is uncolored).
* @param Int gridIndex The keyform's grid index.
* @return Rgb? The multiply color, or null when color is absent.
*/
fun multiplyForKeyform(colorBase: Int?, gridIndex: Int): Rgb? = multiplyAtRow(keyformRow(colorBase, gridIndex))
/**
* Screen-color at keyform [gridIndex] of an object whose color table starts at [colorBase].
*
* @param Int? colorBase The object's base row (null or -1 when the object is uncolored).
* @param Int gridIndex The keyform's grid index.
* @return Rgb? The screen color, or null when color is absent.
*/
fun screenForKeyform(colorBase: Int?, gridIndex: Int): Rgb? = screenAtRow(keyformRow(colorBase, gridIndex))
/**
* Resolves an object's keyform row, collapsing "uncolored" to the negative sentinel the
* row accessors already treat as absent.
*
* @param Int? colorBase The object's base row (null or -1 when the object is uncolored).
* @param Int gridIndex The keyform's grid index.
* @return Int The absolute row, or -1 when the object carries no color.
*/
private fun keyformRow(colorBase: Int?, gridIndex: Int): Int =
if (colorBase == null || colorBase < 0) {
-1
} else {
colorBase + gridIndex
}
}
/**
* The per-keyform value tables shared by the base keyforms and the blend-shape delta rows.
*
* MOC3 §5.6 appends a record's delta rows AFTER the base rows of these same tables, so a base
* keyform and a delta differ only in which row they address. That is why they are read once here
* and handed to both paths. Per-type structural tables (a warp's rows/columns, a drawable's UVs,
* any id or flag column) are NOT shared and stay with their own decoder.
*/
internal class KeyformValueTables(sections: MocSections) {
/** Art-mesh keyform -> packed-position offset (§5.6 section 70, indexing into 71). */
val positionIndex: IntArray = sections.intArray(Section.KEYFORM_POSITION_INDEX)
/** Warp keyform -> packed-position offset; a table distinct from [positionIndex] (section 60). */
val warpPositionIndex: IntArray = sections.intArray(Section.WARP_KEYFORM_INDEX)
/** The packed position blocks both index tables point into (section 71). */
val positionValues: FloatArray = sections.floatArray(Section.KEYFORM_POSITION_VALUES)
/** Part draw-order rows (section 58). */
val partDrawOrder: FloatArray = sections.floatArray(Section.PART_DRAW_ORDER)
/** Warp opacity rows (section 59). */
val warpOpacity: FloatArray = sections.floatArray(Section.WARP_OPACITY)
/** Art-mesh opacity rows (section 68). */
val artMeshOpacity: FloatArray = sections.floatArray(Section.ARTMESH_OPACITY)
/** Art-mesh draw-order rows (section 69). */
val artMeshDrawOrder: FloatArray = sections.floatArray(Section.ARTMESH_DRAW_ORDER)
/** Rotation opacity rows (section 61); a rotation delta indexes the affine tables directly. */
val rotationOpacity: FloatArray = sections.floatArray(Section.ROTATION_OPACITY)
/** Rotation angle rows (section 62). */
val rotationAngle: FloatArray = sections.floatArray(Section.ROTATION_ANGLE)
/** Rotation pivot X rows (section 63). */
val rotationOriginX: FloatArray = sections.floatArray(Section.ROTATION_ORIGIN_X)
/** Rotation pivot Y rows (section 64). */
val rotationOriginY: FloatArray = sections.floatArray(Section.ROTATION_ORIGIN_Y)
/** Rotation scale rows (section 65). */
val rotationScale: FloatArray = sections.floatArray(Section.ROTATION_SCALE)
/** Rotation X-reflection flags (section 66). */
val rotationReflectX: IntArray = sections.intArray(Section.ROTATION_REFLECT_X)
/** Rotation Y-reflection flags (section 67). */
val rotationReflectY: IntArray = sections.intArray(Section.ROTATION_REFLECT_Y)
}
@@ -0,0 +1,314 @@
package org.umamo.format.moc3.decode
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.moc.MocModel
import org.umamo.format.moc3.moc.MocSections
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.moc.Sections
import org.umamo.format.moc3.model.BlendShape
import org.umamo.format.moc3.model.Glue
import org.umamo.format.moc3.model.GlueVertexPair
import org.umamo.format.moc3.model.Offscreen
import org.umamo.format.moc3.model.OffscreenKeyform
import org.umamo.format.moc3.model.Part
import org.umamo.format.moc3.model.RenderOrderChild
import org.umamo.format.moc3.model.RenderOrderGroup
import org.umamo.format.moc3.model.RotationDeformer
import org.umamo.format.moc3.model.WarpDeformer
/**
* Resolves a parsed [MocModel] into the semantic [MocDocument]: the keyform-binding grid and each
* object's per-keyform values (vertex positions, opacity, draw-order, color, deformer transforms).
*
* Reads the typed Layer-1 sections and follows the base/index tables - it does not evaluate the
* model (no interpolation/cascade). Blend shapes (MOC3 v4+) and offscreens (MOC3 v6) are assembled
* too. Every section index is modeled in [Section], so nothing is left to raw access.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
public object MocDecoder {
/**
* Decodes [model] into a [MocDocument].
*
* @param MocModel model A parsed `.moc3` container.
* @return MocDocument The semantic model.
*/
public fun decode(model: MocModel): MocDocument {
val sections = model.sections
val deformerCount = model.deformerCount
val drawables = model.drawables()
val bindings = MocBindingResolver(sections)
bindings.registerStoredBindings(model.countInfo.getOrElse(Sections.CI_KEYFORM_BINDINGS) { 0 })
// ---- value tables ----
val colorTables = ColorTables(sections)
val keyformValues = KeyformValueTables(sections)
// PARTS
val partKeyformBinding = sections.intArray(Section.PART_KEYFORM_BINDING)
val partKeyformBase = sections.intArray(Section.PART_KEYFORM_BASE)
// s7/s8 are a pair whose split is unpinned (both are 1 corpus-wide); take s7 and default to
// visible when a stripped file omits it.
val partVisible = sections.intArray(Section.PART_VISIBLE_ARTMESHES)
val partList =
model.parts().mapIndexed { partIndex, part ->
val keyformBinding = partKeyformBinding[partIndex] // for parts, 0 means static (no binding)
val gridSize = bindings.staticAwareGridSize(keyformBinding)
Part(
part.id,
part.parentPartIndex,
keyformBinding,
FloatArray(gridSize) { keyIndex -> keyformValues.partDrawOrder[partKeyformBase[partIndex] + keyIndex] },
isVisible = partVisible.getOrElse(partIndex) { 1 } != 0,
)
}
// DEFORMERS
val decodedDeformers = DeformerDecoder(sections, bindings, colorTables, keyformValues).decodeAll(deformerCount)
val deformerList = decodedDeformers.deformers
// ART MESHES
// MASK_INDEX_DATA is shared: the offscreen entries are its prefix and the drawables' masks
// follow, so both decoders read the one table (MOC3 v6 §5.6 section 80).
val maskData = sections.intArray(Section.MASK_INDEX_DATA)
val artMeshList = MocArtMeshDecoder(sections, bindings, colorTables, keyformValues, maskData).decodeAll(drawables)
// GLUES
val glueList = decodeGlues(sections)
// Register glue bindings in the cache like every other object kind: a glue names a binding
// from the same shared table (MOC3.md §5.6), and without this a glue-exclusive binding would
// be missing from MocDocument.keyformBinding (dropping the glue's parameter-driven intensity
// downstream) AND from MocDocument.bindings (dropping its table rows from a re-bake).
for (glue in glueList) {
bindings.binding(glue.keyformBindingIndex)
}
// RENDER-ORDER GROUPS
val groupList =
decodeRenderOrderGroups(sections, model.countInfo.getOrElse(Sections.CI_RENDER_ORDER_GROUPS) { 0 })
// BLEND SHAPES (MOC3 v4+)
// MOC3 §5.6: blend delta rows share the base keyforms' value tables (appended after the
// base rows at each record's RECORD_BASE), so the extraction needs the same tables plus
// each target object's payload size (warp control-point count, drawable vertex count).
val blendDeltaTables =
BlendDeltaTables(
keyformValues = keyformValues,
colorTables = colorTables,
warpControlPointCounts = decodedDeformers.warpControlPointCounts,
drawableVertexCounts = IntArray(drawables.size) { drawableIndex -> drawables[drawableIndex].vertexCount },
colorDeltaRowStart =
model.countInfo.getOrElse(Sections.CI_OFFSCREEN_KEYFORMS) { 0 } +
deformerList.sumOf { deformer ->
when (deformer) {
is WarpDeformer -> deformer.keyforms.size
is RotationDeformer -> deformer.keyforms.size
}
} +
artMeshList.sumOf { it.keyforms.size },
)
val blendShapeList =
decodeBlendShapes(
sections,
model.parameterCount,
bindings.keyPositions,
decodedDeformers.warpToDeformer,
decodedDeformers.rotationToDeformer,
blendDeltaTables,
)
// OFFSCREENS (MOC3 v6)
// The offscreen mask entries are the PREFIX of MASK_INDEX_DATA, addressed per offscreen by
// s158 (the cumulative scan of s159, offset from the block start - MOC3 §5.6 section 80).
val offscreenList =
decodeOffscreens(
sections,
model.countInfo.getOrElse(Sections.CI_OFFSCREENS) { 0 },
partList,
colorTables,
maskData,
)
// Probed last, and deliberately so: it measures the trailing region against the bindings
// registered by every object kind above, the glue pass included.
val keyPositionsHasParameterUnion = bindings.hasParameterUnionRegion(blendShapeList.isEmpty())
return MocDocument(
version = model.version,
canvas = model.canvasInfo,
parameters = model.parameters(),
keyformBindings = bindings.collected,
parts = partList,
deformers = deformerList,
artMeshes = artMeshList,
glues = glueList,
renderOrderGroups = groupList,
blendShapes = blendShapeList,
offscreens = offscreenList,
keyPositionsHasParameterUnion = keyPositionsHasParameterUnion,
)
}
/**
* Decodes the blend-shape records (MOC3 v4+ for meshes/warps, MOC3 v5+ for rotations and parts).
*
* @param MocSections sections The model's typed sections.
* @param Int parameterCount Number of parameters (sizes the per-parameter binding ranges).
* @param FloatArray keyPositions The shared key-position table.
* @param List<Int> warpToDeformer Maps a warp local index to its deformer index.
* @param List<Int> rotationToDeformer Maps a rotation local index to its deformer index.
* @param BlendDeltaTables deltaTables The shared value tables the delta rows live in.
* @return List<BlendShape> The decoded blend-shape records (empty when absent).
*/
private fun decodeBlendShapes(
sections: MocSections,
parameterCount: Int,
keyPositions: FloatArray,
warpToDeformer: List<Int>,
rotationToDeformer: List<Int>,
deltaTables: BlendDeltaTables,
): List<BlendShape> {
if (!sections.isPresent(Section.BLENDSHAPE_PARAMETER_BEGIN)) {
return emptyList()
}
return BlendShapeDecoder(sections, parameterCount, keyPositions, deltaTables)
.decodeAll(warpToDeformer, rotationToDeformer)
}
/**
* Decodes the offscreen render targets (moc 6), including their per-keyform opacity/color and
* mask indices. An offscreen's keyforms ride its owner part's keyform grid (no offscreen
* keyform-binding section exists; MOC3 §5.6, OffscreenKeyformProbeTest): opacity rows in
* section 161 and the color tables' PREFIX rows are laid out per offscreen in offscreen order.
*
* @param MocSections sections The model's typed sections.
* @param Int count Number of offscreens from CountInfo.
* @param List<Part> parts The decoded parts (their grids size the keyform runs).
* @param ColorTables colorTables The shared color tables (§5.6 sections 108-113); an offscreen's
* rows are the block's prefix, so they address it by row directly.
* @param IntArray maskData The full MASK_INDEX_DATA table (§5.6 section 80).
* @return List<Offscreen> The decoded offscreens (empty when absent).
*/
private fun decodeOffscreens(
sections: MocSections,
count: Int,
parts: List<Part>,
colorTables: ColorTables,
maskData: IntArray,
): List<Offscreen> {
if (count == 0 || !sections.isPresent(Section.OFFSCREEN_OWNER_PART)) {
return emptyList()
}
val owner = sections.intArray(Section.OFFSCREEN_OWNER_PART)
val flags = sections.byteArray(Section.OFFSCREEN_CONSTANT_FLAGS)
val blendModes = sections.intArray(Section.OFFSCREEN_BLEND_MODE) // one packed value per offscreen
val maskCounts = sections.intArray(Section.OFFSCREEN_MASK_COUNT)
val maskBases = sections.intArray(Section.OFFSCREEN_MASK_BASE)
val opacity = sections.floatArray(Section.OFFSCREEN_OPACITY)
var keyformRowCursor = 0
return (0 until count).map { offscreenIndex ->
val keyformCount = parts[owner[offscreenIndex]].drawOrderKeyforms.size
val keyforms =
(0 until keyformCount).map { keyIndex ->
val keyformRow = keyformRowCursor + keyIndex
OffscreenKeyform(
opacity[keyformRow],
colorTables.multiplyAtRow(keyformRow),
colorTables.screenAtRow(keyformRow),
)
}
keyformRowCursor += keyformCount
// MOC3 v6 §5.6 s158: the offscreen's masks sit at the s158 offset from the BLOCK START -
// the offscreen entries are the block's prefix, before the drawables' masks (pinned on
// Model A: pupil offscreens clip the Whites masks, matching the CMO3 clipGuidList).
val maskIndices = maskData.copyOfRange(maskBases[offscreenIndex], maskBases[offscreenIndex] + maskCounts[offscreenIndex])
Offscreen(
owner[offscreenIndex],
flags[offscreenIndex].toInt() and 0xFF,
blendModes[offscreenIndex],
maskCounts[offscreenIndex],
keyforms,
maskIndices,
)
}
}
/**
* Decodes the glues (seam-welds between art meshes).
*
* @param MocSections sections The model's typed sections.
* @return List<Glue> The decoded glues (empty when absent).
*/
private fun decodeGlues(sections: MocSections): List<Glue> {
val meshA = sections.intArray(Section.GLUE_MESH_A)
if (meshA.isEmpty()) {
return emptyList()
}
val meshB = sections.intArray(Section.GLUE_MESH_B)
val glueId = sections.idArray(Section.GLUE_ID)
val keyformBinding = sections.intArray(Section.GLUE_KEYFORM_BINDING)
val glueVertexStart = sections.intArray(Section.GLUE_VERTEX_START)
val glueVertexCount = sections.intArray(Section.GLUE_VERTEX_COUNT)
val keyOffset = sections.intArray(Section.GLUE_KEY_OFFSET)
val keyCount = sections.intArray(Section.GLUE_KEY_COUNT)
val weights = sections.floatArray(Section.GLUE_WEIGHTS)
val indices = sections.shortArray(Section.GLUE_VERTEX_INDICES)
val intensities = sections.floatArray(Section.GLUE_INTENSITIES)
return (meshA.indices).map { glueIndex ->
val vertexStartIndex = glueVertexStart[glueIndex]
val pairCount = glueVertexCount[glueIndex] / 2
val pairs =
(0 until pairCount).map { pairIndex ->
GlueVertexPair(
indices[vertexStartIndex + 2 * pairIndex].toInt() and 0xFFFF,
indices[vertexStartIndex + 2 * pairIndex + 1].toInt() and 0xFFFF,
weights[vertexStartIndex + 2 * pairIndex],
weights[vertexStartIndex + 2 * pairIndex + 1],
)
}
Glue(
// A stripped file without s90 leaves the id blank rather than failing the decode.
glueId.getOrElse(glueIndex) { "" },
meshA[glueIndex],
meshB[glueIndex],
keyformBinding[glueIndex],
pairs,
intensities.copyOfRange(keyOffset[glueIndex], keyOffset[glueIndex] + keyCount[glueIndex]),
)
}
}
/**
* Decodes the render-order group tree (the draw-order hierarchy).
*
* @param MocSections sections The model's typed sections.
* @param Int groupCount Number of render-order groups from CountInfo.
* @return List<RenderOrderGroup> The decoded groups (empty when absent).
*/
private fun decodeRenderOrderGroups(
sections: MocSections,
groupCount: Int,
): List<RenderOrderGroup> {
if (groupCount == 0) {
return emptyList()
}
val childCount = sections.intArray(Section.RENDER_ORDER_CHILD_COUNT)
val childKind = sections.intArray(Section.RENDER_ORDER_CHILD_KIND)
val childIndex = sections.intArray(Section.RENDER_ORDER_CHILD_INDEX)
val childGroupIndex = sections.intArray(Section.RENDER_ORDER_GROUP_INDEX)
var childBase = 0
return (0 until groupCount).map { groupIndex ->
val children =
(0 until childCount[groupIndex]).map { childOrdinal ->
RenderOrderChild(
childKind[childBase + childOrdinal],
childIndex[childBase + childOrdinal],
childGroupIndex[childBase + childOrdinal],
)
}
childBase += childCount[groupIndex]
RenderOrderGroup(children)
}
}
}
@@ -0,0 +1,166 @@
package org.umamo.format.moc3.decode
import org.umamo.format.moc3.moc.MocSections
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.model.Deformer
import org.umamo.format.moc3.model.RotationDeformer
import org.umamo.format.moc3.model.RotationKeyform
import org.umamo.format.moc3.model.WarpDeformer
import org.umamo.format.moc3.model.WarpKeyform
/** The decoded deformer block, plus the index maps and payload sizes the blend path needs. */
internal class DecodedDeformers(
val deformers: List<Deformer>,
/** Warp local index -> deformer index; blend-shape warp records are stored against the local one. */
val warpToDeformer: List<Int>,
/** Rotation local index -> deformer index, for the same reason. */
val rotationToDeformer: List<Int>,
/** Control points per warp, which sizes both a base warp keyform and a warp delta payload. */
val warpControlPointCounts: IntArray,
)
/**
* Decodes the deformer block into typed [WarpDeformer]s and [RotationDeformer]s.
*
* Both kinds share one deformer index space and one common head (MOC3 §5.6 sections 11-15), but
* each kind's own tables are densely packed over only its own members. So the walk advances the
* shared index while carrying a separate local cursor per kind, and every per-type read is by that
* local index, never the deformer index. Those local indices are also how blend-shape records
* name their target, which is what [DecodedDeformers] carries the maps for.
*/
internal class DeformerDecoder(
sections: MocSections,
private val bindings: MocBindingResolver,
private val colorTables: ColorTables,
private val keyformValues: KeyformValueTables,
) {
private val deformerType = sections.intArray(Section.DEFORMER_TYPE)
private val deformerParent = sections.intArray(Section.DEFORMER_PARENT)
// The block's common head (MOC3 §5.6 S11-S15).
private val deformerId = sections.idArray(Section.DEFORMER_ID)
// Section 12 is the same binding that the warp/rotation sections 19/25 have.
// Warp and Rotation have their own keyform binding which duplicates the deformer binding.
// We don't necessarily need it, but we read and write it since there is a chance it might cause a MOC3
// validation error in the runtime.
private val deformerKeyformBinding = sections.intArray(Section.DEFORMER_KEYFORM_BINDING)
private val deformerIsVisible = sections.intArray(Section.DEFORMER_IS_VISIBLE)
private val deformerIsEnabled = sections.intArray(Section.DEFORMER_IS_ENABLED)
private val deformerParentPart = sections.intArray(Section.DEFORMER_PARENT_PART)
private val warpKeyformBinding = sections.intArray(Section.WARP_KEYFORM_BINDING)
private val warpKeyformBase = sections.intArray(Section.WARP_KEYFORM_BASE)
private val warpRows = sections.intArray(Section.WARP_ROWS)
private val warpColumns = sections.intArray(Section.WARP_COLUMNS)
private val warpMode = if (sections.isPresent(Section.WARP_MODE)) sections.intArray(Section.WARP_MODE) else null
private val warpColorBase =
if (sections.isPresent(Section.WARP_COLOR_BASE)) sections.intArray(Section.WARP_COLOR_BASE) else null
private val rotationKeyformBinding = sections.intArray(Section.ROTATION_KEYFORM_BINDING)
private val rotationKeyformBase = sections.intArray(Section.ROTATION_KEYFORM_BASE)
private val rotationBaseAngle = sections.floatArray(Section.ROTATION_BASE_ANGLE)
private val rotationColorBase =
if (sections.isPresent(Section.ROTATION_COLOR_BASE)) sections.intArray(Section.ROTATION_COLOR_BASE) else null
/** Control points per warp: an (rows + 1) x (columns + 1) lattice of them. */
private val warpControlPointCounts =
IntArray(warpRows.size) { warpLocalIndex ->
(warpRows[warpLocalIndex] + 1) * (warpColumns[warpLocalIndex] + 1)
}
/**
* Decodes every deformer, dispatching on the section 11 type column.
*
* @param Int deformerCount The model's deformer count.
* @return DecodedDeformers The deformers in index order, with the per-kind index maps.
*/
fun decodeAll(deformerCount: Int): DecodedDeformers {
var nextWarpLocal = 0
var nextRotationLocal = 0
val warpToDeformer = ArrayList<Int>()
val rotationToDeformer = ArrayList<Int>()
val deformers = ArrayList<Deformer>(deformerCount)
for (deformerIndex in 0 until deformerCount) {
if (deformerType[deformerIndex] == 0) {
warpToDeformer.add(deformerIndex)
deformers.add(warpDeformer(deformerIndex, nextWarpLocal++))
} else {
rotationToDeformer.add(deformerIndex)
deformers.add(rotationDeformer(deformerIndex, nextRotationLocal++))
}
}
return DecodedDeformers(deformers, warpToDeformer, rotationToDeformer, warpControlPointCounts)
}
/**
* Builds one warp deformer and its FFD lattice keyforms.
*
* @param Int deformerIndex Its index in the shared deformer space (the common head's row).
* @param Int warpLocalIndex Its index among warps (every per-warp table's row).
* @return WarpDeformer The decoded deformer.
*/
private fun warpDeformer(deformerIndex: Int, warpLocalIndex: Int): WarpDeformer {
val keyformBinding = warpKeyformBinding[warpLocalIndex]
val keyformBase = warpKeyformBase[warpLocalIndex]
val controlPointCount = warpControlPointCounts[warpLocalIndex]
val keyforms =
(0 until bindings.binding(keyformBinding).gridSize).map { gridIndex ->
val positionOffset = keyformValues.warpPositionIndex[keyformBase + gridIndex]
WarpKeyform(
keyformValues.positionValues.copyOfRange(positionOffset, positionOffset + controlPointCount * 2),
keyformValues.warpOpacity[keyformBase + gridIndex],
colorTables.multiplyForKeyform(warpColorBase?.get(warpLocalIndex), gridIndex),
colorTables.screenForKeyform(warpColorBase?.get(warpLocalIndex), gridIndex),
)
}
return WarpDeformer(
id = deformerId.getOrElse(deformerIndex) { "" },
keyformBindingIndex = keyformBinding,
isVisible = deformerIsVisible.getOrElse(deformerIndex) { 1 } != 0,
isEnabled = deformerIsEnabled.getOrElse(deformerIndex) { 1 } != 0,
parentPartIndex = deformerParentPart.getOrElse(deformerIndex) { -1 },
parentDeformerIndex = deformerParent[deformerIndex],
rows = warpRows[warpLocalIndex],
columns = warpColumns[warpLocalIndex],
mode = warpMode?.get(warpLocalIndex) ?: 0,
keyforms = keyforms,
)
}
/**
* Builds one rotation deformer and its pivot-transform keyforms.
*
* @param Int deformerIndex Its index in the shared deformer space (the common head's row).
* @param Int rotationLocalIndex Its index among rotations (every per-rotation table's row).
* @return RotationDeformer The decoded deformer.
*/
private fun rotationDeformer(deformerIndex: Int, rotationLocalIndex: Int): RotationDeformer {
val keyformBinding = rotationKeyformBinding[rotationLocalIndex]
val keyformBase = rotationKeyformBase[rotationLocalIndex]
val keyforms =
(0 until bindings.binding(keyformBinding).gridSize).map { gridIndex ->
RotationKeyform(
keyformValues.rotationOriginX[keyformBase + gridIndex],
keyformValues.rotationOriginY[keyformBase + gridIndex],
keyformValues.rotationAngle[keyformBase + gridIndex],
keyformValues.rotationScale[keyformBase + gridIndex],
keyformValues.rotationReflectX[keyformBase + gridIndex] != 0,
keyformValues.rotationReflectY[keyformBase + gridIndex] != 0,
keyformValues.rotationOpacity[keyformBase + gridIndex],
colorTables.multiplyForKeyform(rotationColorBase?.get(rotationLocalIndex), gridIndex),
colorTables.screenForKeyform(rotationColorBase?.get(rotationLocalIndex), gridIndex),
)
}
return RotationDeformer(
id = deformerId.getOrElse(deformerIndex) { "" },
keyformBindingIndex = keyformBinding,
isVisible = deformerIsVisible.getOrElse(deformerIndex) { 1 } != 0,
isEnabled = deformerIsEnabled.getOrElse(deformerIndex) { 1 } != 0,
parentPartIndex = deformerParentPart.getOrElse(deformerIndex) { -1 },
parentDeformerIndex = deformerParent[deformerIndex],
baseAngle = rotationBaseAngle[rotationLocalIndex],
keyforms = keyforms,
)
}
}
@@ -0,0 +1,168 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.model.RenderOrderChild
/**
* Synthesizes the glue, render-order, and offscreen tables - the object kinds whose packing is
* deterministic but which own no keyform value tables of their own.
*
* @param MocLoweringContext context The shared lowering derivations.
* @return Map Section index → element-region bytes.
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
internal fun auxiliarySections(context: MocLoweringContext): Map<Int, ByteArray> {
val doc = context.doc
val sink = SectionSink(doc.version)
// glue value tables
if (doc.glues.isNotEmpty()) {
val vertexStart = ArrayList<Int>()
val glueVertexCount = ArrayList<Int>()
val keyOffset = ArrayList<Int>()
val keyCount = ArrayList<Int>()
val weights = ArrayList<Float>()
val indices = ArrayList<Short>()
val intensities = ArrayList<Float>()
for (glue in doc.glues) {
vertexStart.add(weights.size)
glueVertexCount.add(glue.pairs.size * 2)
for (pair in glue.pairs) {
weights.add(pair.weightA)
weights.add(pair.weightB)
indices.add(pair.vertexA.toShort())
indices.add(pair.vertexB.toShort())
}
keyOffset.add(intensities.size)
keyCount.add(glue.intensityKeyforms.size)
glue.intensityKeyforms.forEach { intensities.add(it) }
}
sink.putInts(Section.GLUE_VERTEX_START, vertexStart)
sink.putInts(Section.GLUE_VERTEX_COUNT, glueVertexCount)
sink.putInts(Section.GLUE_KEY_OFFSET, keyOffset)
sink.putInts(Section.GLUE_KEY_COUNT, keyCount)
sink.putFloats(Section.GLUE_WEIGHTS, weights)
sink.putFloats(Section.GLUE_INTENSITIES, intensities)
sink.putShorts(Section.GLUE_VERTEX_INDICES, indices)
}
// render-order group tree
if (doc.renderOrderGroups.isNotEmpty()) {
val groups = doc.renderOrderGroups
val childCount = ArrayList<Int>()
val childKind = ArrayList<Int>()
val childIndex = ArrayList<Int>()
val childGroupIndex = ArrayList<Int>()
for (group in groups) {
childCount.add(group.children.size)
for (child in group.children) {
childKind.add(child.kind)
childIndex.add(child.index)
childGroupIndex.add(child.groupIndex)
}
}
sink.putInts(Section.RENDER_ORDER_CHILD_COUNT, childCount)
sink.putInts(Section.RENDER_ORDER_CHILD_KIND, childKind)
sink.putInts(Section.RENDER_ORDER_CHILD_INDEX, childIndex)
sink.putInts(Section.RENDER_ORDER_GROUP_INDEX, childGroupIndex)
// Per-group render count (83) and child draw-order extent (84/85), which the runtime reads. A kind-0 child's draw order is its
// mesh's; a kind-1 child's is its sub-group part's; the render count recurses into sub-groups and
// counts an extra slot for a sub-group part that owns an offscreen. Draw order = floor(0.001+value).
val ownerParts = doc.offscreens.map { it.ownerPartIndex }.toHashSet()
val renderCountMemo = HashMap<Int, Int>()
/**
* Total render-index count of group [groupIndex] (recursive, with offscreen-owner slots).
*
* @param Int groupIndex The render-order group index.
* @return Int The recursive render count.
*/
fun renderCount(groupIndex: Int): Int =
renderCountMemo.getOrPut(groupIndex) {
groups[groupIndex].children.sumOf { child ->
if (child.kind == 0) {
1
} else {
(if (child.index in ownerParts) 1 else 0) + renderCount(child.groupIndex)
}
}
}
/**
* The integer draw order of one render-order [child] (its mesh's, or its sub-group part's).
*
* @param RenderOrderChild child A render-order child.
* @return Int The floored draw order (`floor(0.001 + value)`).
*/
fun childDrawOrder(child: RenderOrderChild): Int {
val drawOrderValue =
if (child.kind == 0) {
doc.artMeshes[child.index].keyforms.first().drawOrder
} else {
doc.parts[child.index].drawOrderKeyforms.first()
}
return (0.001f + drawOrderValue).toInt()
}
val renderCounts = ArrayList<Int>()
val maxDraw = ArrayList<Int>()
val minDraw = ArrayList<Int>()
for (groupIndex in groups.indices) {
renderCounts.add(renderCount(groupIndex))
val childOrders = groups[groupIndex].children.map(::childDrawOrder)
// MOC3 §5.6: an EMPTY group stores the max/min fold identities (-INT_MAX / INT_MAX),
// not a 500 default - probed on the ModelWithOffscreen family's childless groups.
maxDraw.add(childOrders.maxOrNull() ?: -Int.MAX_VALUE)
minDraw.add(childOrders.minOrNull() ?: Int.MAX_VALUE)
}
sink.putInts(Section.RENDER_ORDER_GROUP_RENDER_COUNT, renderCounts)
sink.putInts(Section.RENDER_ORDER_GROUP_MAX_DRAW_ORDER, maxDraw)
sink.putInts(Section.RENDER_ORDER_GROUP_MIN_DRAW_ORDER, minDraw)
}
// offscreens: per-object scalar sections + keyform tables
if (doc.offscreens.isNotEmpty()) {
sink.putInts(Section.OFFSCREEN_OWNER_PART, doc.offscreens.map { it.ownerPartIndex })
sink.putBytes(Section.OFFSCREEN_CONSTANT_FLAGS, ByteArray(doc.offscreens.size) { doc.offscreens[it].constantFlags.toByte() })
sink.putInts(Section.OFFSCREEN_BLEND_MODE, doc.offscreens.map { it.blendMode })
sink.putInts(Section.OFFSCREEN_MASK_COUNT, doc.offscreens.map { it.maskCount })
// 152: the per-part inverse of OFFSCREEN_OWNER_PART (-1 for offscreen-less parts).
val offscreenByPart = IntArray(doc.parts.size) { -1 }
for ((offscreenIndex, offscreen) in doc.offscreens.withIndex()) {
if (offscreen.ownerPartIndex in offscreenByPart.indices) {
offscreenByPart[offscreen.ownerPartIndex] = offscreenIndex
}
}
sink.putInts(Section.OFFSCREEN_BY_PART, offscreenByPart.toList())
// 160 gets the SAME inverse map, and it must be written: the runtime reads it as a per-part
// offscreen index, so leaving it empty makes it read the neighbouring section's bytes as part
// indices and take the core down (not a rejected file - a segfault inside it).
//
// The two columns are byte-identical in every corpus file but modelA, where 152 is the exact
// inverse of the offscreen owner column (155) and 160 names a different, larger set of parts
// that matches no owner. Which makes 152 the reconstructible one and 160 an editor-internal
// artifact, in the same class as the keyform-binding numbering: we write the consistent
// inverse in both rather than reproduce a divergence we cannot derive.
sink.putInts(Section.OFFSCREEN_BY_PART_ALIAS, offscreenByPart.toList())
// 158: cumulative mask base (the scan of 159; MOC3 §5.6, OffscreenKeyformProbeTest).
val maskBases = ArrayList<Int>()
var maskBaseCursor = 0
for (offscreen in doc.offscreens) {
maskBases.add(maskBaseCursor)
maskBaseCursor += offscreen.maskCount
}
sink.putInts(Section.OFFSCREEN_MASK_BASE, maskBases)
// Keyform tables only when the typed extraction populated them (else carried).
if (doc.offscreens.all { it.keyforms.isNotEmpty() }) {
val offscreenOpacities = doc.offscreens.flatMap { offscreen -> offscreen.keyforms.map { it.opacity } }
sink.putFloats(Section.OFFSCREEN_OPACITY, offscreenOpacities)
// 162/163: keyform → color-prefix row maps; identity because the offscreen keyform
// rows ARE the color tables' prefix, in offscreen order.
val identityRows = (0 until offscreenOpacities.size).toList()
sink.putInts(Section.OFFSCREEN_KEYFORM_MULTIPLY_ROW, identityRows)
sink.putInts(Section.OFFSCREEN_KEYFORM_SCREEN_ROW, identityRows)
}
}
return sink.toMap()
}
@@ -0,0 +1,179 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.model.BlendShape
import org.umamo.format.moc3.model.BlendShapeTarget
/**
* Synthesizes the blend-shape record/binding/limit sections from [context] (MOC3 v4+ §5.6:
* 115-136 plus the per-kind object trios 125-130/143-148). Bindings and the limit sub-binding
* pool are re-deduplicated from the per-record expansions (the decoder expands the pool per
* record); RECORD_BASE is recomputed as the per-kind running cursor after the base keyforms,
* which reproduces the decoded values for an unedited document.
*
* @param MocLoweringContext context The shared lowering derivations.
* @return Map Section index → element-region bytes. A document with no blend records still yields
* the per-parameter binding ranges 115/116, which a v4+ file carries either way; only a
* document with no parameters at all yields an empty map.
*/
internal fun blendShapeSections(context: MocLoweringContext): Map<Int, ByteArray> {
val doc = context.doc
val sink = SectionSink(doc.version)
val layout = context.blendLayout
// 115/116: per-parameter binding ranges. A binding-less parameter stores begin = 0, NOT the
// running cumulative (probed on Model A/B/C - unlike SUBSTART's carry convention), unless the
// parameter is itself blend-shape-typed, which stores -1 instead.
//
// Written from the layout on EVERY document, blend records or not. A v4+ blend-free file still
// carries both columns, and an empty layout produces exactly what that file holds, so one path
// covers both kinds of document - the alternative is a second copy of the -1/0 filler rule that
// has to be kept in agreement with this one by hand. Below v4 the sink drops both sections.
//
// A document with NO parameters writes neither: the columns are per-parameter, and emitting
// them empty would override a section `MocEncoder.bake` would otherwise carry from its reference.
if (doc.parameters.isNotEmpty()) {
sink.putInts(Section.BLENDSHAPE_PARAMETER_BEGIN, layout.parameterBegin.toList())
sink.putInts(Section.BLENDSHAPE_PARAMETER_COUNT, layout.parameterBindingCount.toList())
}
if (!context.hasBlendShapes) {
return sink.toMap()
}
// 117-119: per-binding key runs (absolute float offsets into KEY_POSITIONS' second region,
// after the main-grid keys) + neutral indices.
val mainGridKeyTotal = context.mainGridKeyTotal
val bindingKeyOffsets = ArrayList<Int>()
var bindingKeyCursor = mainGridKeyTotal
for (bindingKeys in layout.bindingKeys) {
bindingKeyOffsets.add(bindingKeyCursor)
bindingKeyCursor += bindingKeys.size
}
sink.putInts(Section.BLENDSHAPE_BINDING_KEY_OFFSET, bindingKeyOffsets)
sink.putInts(Section.BLENDSHAPE_BINDING_KEY_COUNT, layout.bindingKeys.map { it.size })
sink.putInts(Section.BLENDSHAPE_BINDING_NEUTRAL, layout.bindingNeutral.toList())
// 120-122: per-record binding refs, value-table bases (per-kind running cursors after the
// base keyforms), and the redundant key-count copy.
sink.putInts(Section.BLENDSHAPE_RECORD_BINDING, layout.bindingIndexOfRecord.toList())
val warps = context.warps
val rotations = context.rotations
val kindCursors =
hashMapOf(
BlendShapeTarget.WARP to warps.sumOf { it.keyforms.size },
BlendShapeTarget.ART_MESH to doc.artMeshes.sumOf { it.keyforms.size },
BlendShapeTarget.ROTATION to rotations.sumOf { it.keyforms.size },
BlendShapeTarget.PART to doc.parts.sumOf { it.drawOrderKeyforms.size },
)
val recordBases = ArrayList<Int>()
for (record in layout.recordsInFileOrder) {
val cursor = kindCursors.getValue(record.target)
recordBases.add(cursor)
kindCursors[record.target] = cursor + record.keyPositions.size
}
sink.putInts(Section.BLENDSHAPE_RECORD_BASE, recordBases)
sink.putInts(Section.BLENDSHAPE_RECORD_KEY_COUNT, layout.recordsInFileOrder.map { it.keyPositions.size })
// 123/124 + 131-136: limit corner refs into the deduplicated sub-binding pool. SUBSTART is
// running-cumulative (cornerless records carry the running value).
val substarts = ArrayList<Int>()
val cornerCounts = ArrayList<Int>()
val subIndices = ArrayList<Int>()
var cornerCursor = 0
for (record in layout.recordsInFileOrder) {
substarts.add(cornerCursor)
cornerCounts.add(record.limits.size)
cornerCursor += record.limits.size
for (limit in record.limits) {
subIndices.add(layout.poolIndexOf(limit))
}
}
sink.putInts(Section.BLENDSHAPE_RECORD_SUBSTART, substarts)
sink.putInts(Section.BLENDSHAPE_RECORD_CORNER_COUNT, cornerCounts)
if (layout.pool.isNotEmpty()) {
val subKeyOffsets = ArrayList<Int>()
val subKeyCounts = ArrayList<Int>()
val subKeys = ArrayList<Float>()
val subWeights = ArrayList<Float>()
for (poolEntry in layout.pool) {
subKeyOffsets.add(subKeys.size)
subKeyCounts.add(poolEntry.keyPositions.size)
poolEntry.keyPositions.forEach { subKeys.add(it) }
poolEntry.weights.forEach { subWeights.add(it) }
}
sink.putInts(Section.BLENDSHAPE_SUB_INDEX, subIndices)
sink.putInts(Section.BLENDSHAPE_SUB_PARAMETER, layout.pool.map { it.parameterIndex })
sink.putInts(Section.BLENDSHAPE_SUB_KEY_OFFSET, subKeyOffsets)
sink.putInts(Section.BLENDSHAPE_SUB_KEY_COUNT, subKeyCounts)
sink.putFloats(Section.BLENDSHAPE_SUB_KEYS, subKeys)
sink.putFloats(Section.BLENDSHAPE_SUB_WEIGHT_VALUES, subWeights)
}
// Per-kind object trios: objects owning records (kind-local indices ascending), with each
// object's record range as GLOBAL record indices.
fun putTrio(
records: List<BlendShape>,
recordOffset: Int,
localIndexOf: (Int) -> Int,
objectSection: Section,
startSection: Section,
countSection: Section,
) {
if (records.isEmpty()) {
return
}
val objectIndices = ArrayList<Int>()
val recordStarts = ArrayList<Int>()
val recordCounts = ArrayList<Int>()
for ((recordOrdinal, record) in records.withIndex()) {
val localObjectIndex = localIndexOf(record.targetIndex)
if (objectIndices.isEmpty() || objectIndices.last() != localObjectIndex) {
objectIndices.add(localObjectIndex)
recordStarts.add(recordOffset + recordOrdinal)
recordCounts.add(1)
} else {
recordCounts[recordCounts.size - 1] = recordCounts.last() + 1
}
}
sink.putInts(objectSection, objectIndices)
sink.putInts(startSection, recordStarts)
sink.putInts(countSection, recordCounts)
}
val meshRecordOffset = layout.warpRecords.size
val partRecordOffset = meshRecordOffset + layout.meshRecords.size
val rotationRecordOffset = partRecordOffset + layout.partRecords.size
putTrio(
layout.warpRecords,
0,
{ deformerIndex -> layout.warpLocalByDeformer[deformerIndex] ?: deformerIndex },
Section.BLENDSHAPE_WARP_OBJECT,
Section.BLENDSHAPE_WARP_RECORD_START,
Section.BLENDSHAPE_WARP_RECORD_COUNT,
)
putTrio(
layout.meshRecords,
meshRecordOffset,
{ drawableIndex -> drawableIndex },
Section.BLENDSHAPE_MESH_OBJECT,
Section.BLENDSHAPE_MESH_RECORD_START,
Section.BLENDSHAPE_MESH_RECORD_COUNT,
)
putTrio(
layout.partRecords,
partRecordOffset,
{ partIndex -> partIndex },
Section.BLENDSHAPE_PART_OBJECT,
Section.BLENDSHAPE_PART_RECORD_START,
Section.BLENDSHAPE_PART_RECORD_COUNT,
)
putTrio(
layout.rotationRecords,
rotationRecordOffset,
{ deformerIndex -> layout.rotationLocalByDeformer[deformerIndex] ?: deformerIndex },
Section.BLENDSHAPE_ROTATION_OBJECT,
Section.BLENDSHAPE_ROTATION_RECORD_START,
Section.BLENDSHAPE_ROTATION_RECORD_COUNT,
)
return sink.toMap()
}
@@ -0,0 +1,173 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.model.BlendShapeKeyform
import org.umamo.format.moc3.model.BlendShapeTarget
import org.umamo.format.moc3.model.Rgb
import org.umamo.format.moc3.model.RotationDeformer
import org.umamo.format.moc3.model.WarpDeformer
/**
* Synthesizes the color tables and the per-form row references into them (MOC3 v4+).
*
* The encode-side counterpart of the decoder's ColorTables: one shared row pool that every kind of
* object indexes into, rather than a per-object table. Rows are laid out as a moc-6 offscreen keyform
* PREFIX, then the base rows (deformers in unified order, then art meshes), then the blend records'
* color delta rows - and sections 137-142 are what the runtime dereferences to reach a given form's
* row, so a kind whose reference table is short sends it reading past the pool.
*
* @param MocLoweringContext context The shared lowering derivations.
* @return Map Section index → element-region bytes (empty when the document carries no color data).
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
internal fun colorSections(context: MocLoweringContext): Map<Int, ByteArray> {
val doc = context.doc
val sink = SectionSink(doc.version)
// Layout (MOC3 §5.6): a moc-6 offscreen keyform PREFIX, then the base rows (deformers in
// unified order, then meshes), then the blend records' color delta rows (global record
// order, part records excluded - parts own no color rows). Synthesized whenever any typed
// color data exists; a doc whose offscreens/blends predate the typed extraction (empty
// keyform lists) falls back to carrying via the size guard below.
val offscreenKeyformsTyped = doc.offscreens.all { it.keyforms.isNotEmpty() }
val hasColor =
(offscreenKeyformsTyped || doc.offscreens.isEmpty()) &&
(
doc.deformers.any { deformer ->
(deformer is WarpDeformer && deformer.keyforms.any { it.multiplyColor != null }) ||
(deformer is RotationDeformer && deformer.keyforms.any { it.multiplyColor != null })
} ||
doc.artMeshes.any { mesh -> mesh.keyforms.any { it.multiplyColor != null } } ||
doc.offscreens.any { offscreen -> offscreen.keyforms.any { it.multiplyColor != null } }
)
if (hasColor) {
val multiplyRed = ArrayList<Float>()
val multiplyGreen = ArrayList<Float>()
val multiplyBlue = ArrayList<Float>()
val screenRed = ArrayList<Float>()
val screenGreen = ArrayList<Float>()
val screenBlue = ArrayList<Float>()
/**
* Appends one keyform's multiply/screen colors, defaulting to white/black when absent.
*
* @param Rgb? multiplyColor The keyform's multiply color (null → white identity).
* @param Rgb? screenColor The keyform's screen color (null → black identity).
*/
fun appendColors(multiplyColor: Rgb?, screenColor: Rgb?) {
val multiply = multiplyColor ?: Rgb(1f, 1f, 1f)
val screen = screenColor ?: Rgb(0f, 0f, 0f)
multiplyRed.add(multiply.r)
multiplyGreen.add(multiply.g)
multiplyBlue.add(multiply.b)
screenRed.add(screen.r)
screenGreen.add(screen.g)
screenBlue.add(screen.b)
}
/**
* Appends one blend delta row's colors; an unauthored delta channel is ZERO, not the
* channel's identity (MOC3 §5.6: delta rows are neutral-relative).
*
* @param Rgb? multiplyColor The delta row's multiply color (null → zero).
* @param Rgb? screenColor The delta row's screen color (null → zero).
*/
fun appendDeltaColors(multiplyColor: Rgb?, screenColor: Rgb?) {
appendColors(multiplyColor ?: Rgb(0f, 0f, 0f), screenColor ?: Rgb(0f, 0f, 0f))
}
// MOC3 v6: the offscreen keyform rows prefix the tables, shifting every base below.
for (offscreen in doc.offscreens) {
offscreen.keyforms.forEach { appendColors(it.multiplyColor, it.screenColor) }
}
// Per-FORM color-row references (137-142), one entry per form SLOT of each object kind, in
// that kind's own form order. They are what the runtime dereferences to reach a form's color
// row, so a kind whose table is short or absent sends it reading past the end - which is a
// segfault inside the official core, not a rejected file.
//
// The tail of each table covers that kind's BLEND-SHAPE record rows: the runtime reaches a
// record's color delta through the same indirection, at the record base rather than the
// object base, so the delta rows have to be addressable here too.
val warpColorRefs = ArrayList<Int>()
val rotationColorRefs = ArrayList<Int>()
val meshColorRefs = ArrayList<Int>()
val warpColorBase = ArrayList<Int>()
val rotationColorBase = ArrayList<Int>()
for (deformer in doc.deformers) {
when (deformer) {
is WarpDeformer -> {
warpColorBase.add(multiplyRed.size)
deformer.keyforms.forEach {
warpColorRefs.add(multiplyRed.size)
appendColors(it.multiplyColor, it.screenColor)
}
}
is RotationDeformer -> {
rotationColorBase.add(multiplyRed.size)
deformer.keyforms.forEach {
rotationColorRefs.add(multiplyRed.size)
appendColors(it.multiplyColor, it.screenColor)
}
}
}
}
val meshColorBase = ArrayList<Int>()
for (mesh in doc.artMeshes) {
meshColorBase.add(multiplyRed.size)
mesh.keyforms.forEach {
meshColorRefs.add(multiplyRed.size)
appendColors(it.multiplyColor, it.screenColor)
}
}
// A 4.2-era bake carries no delta region (see hasColorDeltaRows) - mirror its absence so
// the re-synthesized tables end at the base rows and stay byte-exact both ways.
if (context.hasBlendShapes && context.hasColorDeltaRows) {
val blendLayout = context.blendLayout
for (record in blendLayout.recordsInFileOrder) {
if (record.target == BlendShapeTarget.PART) {
continue
}
for (keyform in record.keyforms) {
when (keyform) {
is BlendShapeKeyform.Warp -> {
warpColorRefs.add(multiplyRed.size)
appendDeltaColors(keyform.form.multiplyColor, keyform.form.screenColor)
}
is BlendShapeKeyform.Mesh -> {
meshColorRefs.add(multiplyRed.size)
appendDeltaColors(keyform.form.multiplyColor, keyform.form.screenColor)
}
is BlendShapeKeyform.Rotation -> {
rotationColorRefs.add(multiplyRed.size)
appendDeltaColors(keyform.form.multiplyColor, keyform.form.screenColor)
}
// A part owns no color rows at all, so it contributes no reference either.
is BlendShapeKeyform.Part -> Unit
}
}
}
}
// The multiply and screen tables of each pair are bit-identical corpus-wide (the reference is to
// a ROW, and a row carries both colors), so one list feeds both.
sink.putInts(Section.WARP_FORM_MULTIPLY_ROW, warpColorRefs)
sink.putInts(Section.WARP_FORM_SCREEN_ROW, warpColorRefs)
sink.putInts(Section.ROTATION_FORM_MULTIPLY_ROW, rotationColorRefs)
sink.putInts(Section.ROTATION_FORM_SCREEN_ROW, rotationColorRefs)
sink.putInts(Section.ARTMESH_FORM_MULTIPLY_ROW, meshColorRefs)
sink.putInts(Section.ARTMESH_FORM_SCREEN_ROW, meshColorRefs)
sink.putInts(Section.WARP_COLOR_BASE, warpColorBase)
sink.putInts(Section.ROTATION_COLOR_BASE, rotationColorBase)
sink.putInts(Section.ARTMESH_COLOR_BASE, meshColorBase)
sink.putFloats(Section.COLOR_MULTIPLY_R, multiplyRed)
sink.putFloats(Section.COLOR_MULTIPLY_G, multiplyGreen)
sink.putFloats(Section.COLOR_MULTIPLY_B, multiplyBlue)
sink.putFloats(Section.COLOR_SCREEN_R, screenRed)
sink.putFloats(Section.COLOR_SCREEN_G, screenGreen)
sink.putFloats(Section.COLOR_SCREEN_B, screenBlue)
}
return sink.toMap()
}
@@ -0,0 +1,140 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.io.LittleEndianWriter
import org.umamo.format.moc3.model.BlendShape
import org.umamo.format.moc3.model.BlendShapeKeyform
/**
* Synthesizes the CountInfo block (section 0) from [context]: the per-object-kind counts and the
* cumulative totals the runtime allocates its working buffers from. The per-kind keyform
* totals (6-10, 14) INCLUDE the blend-shape delta rows (MOC3 §5.6: CountInfo counts the full
* shared tables, base plus delta), and fields 23-36 carry the blend-shape and offscreen totals.
*
* Every total is taken from the shared context rather than recomputed, because CountInfo declares
* the extent of tables the other producers write - a second traversal here could disagree with them.
*
* @param MocLoweringContext context The shared lowering derivations (document, per-kind deformer
* lists, blend layout, and the keyform-grid totals).
* @return ByteArray The CountInfo element-region bytes (`u32[fieldCount]`).
*/
internal fun countInfoSection(context: MocLoweringContext): ByteArray {
val doc = context.doc
val warps = context.warps
val rotations = context.rotations
val blendLayout = context.blendLayout.takeIf { context.hasBlendShapes }
fun padded(coordinateCount: Int): Int = (coordinateCount + 15) / 16 * 16
/**
* Sums the record keys of [records] (the per-kind delta-row total).
*
* @param List<BlendShape>? records One kind's records, or null when the doc has no blends.
* @return Int The delta-row total.
*/
fun deltaRowsOf(records: List<BlendShape>?): Int = records?.sumOf { it.keyPositions.size } ?: 0
val positionFloatCount =
warps.sumOf { warp -> warp.keyforms.sumOf { padded(it.controlPoints.size) } } +
doc.artMeshes.sumOf { mesh -> mesh.keyforms.sumOf { padded(it.vertexPositions.size) } } +
(
blendLayout?.let { layout ->
layout.warpRecords.sumOf { record ->
record.keyforms.filterIsInstance<BlendShapeKeyform.Warp>().sumOf { padded(it.form.controlPoints.size) }
} +
layout.meshRecords.sumOf { record ->
record.keyforms.filterIsInstance<BlendShapeKeyform.Mesh>().sumOf { padded(it.form.vertexPositions.size) }
}
} ?: 0
)
// The block widens to 64 words at MOC3 v5, NOT at MOC3 v6: every v5 corpus file's section 0 is 256
// bytes, and a v5 model with rotation blend shapes writes field 33 (LimeBirb). Capping v5 at 32
// would silently drop that field, and the re-decode would then find zero blend-shape rotations.
val fieldCount = if (doc.version.byteValue >= 5) 64 else 32
val countInfo = IntArray(fieldCount)
countInfo[0] = doc.parts.size
countInfo[1] = doc.deformers.size
countInfo[2] = warps.size
countInfo[3] = rotations.size
countInfo[4] = doc.artMeshes.size
countInfo[5] = doc.parameters.size
countInfo[6] = doc.parts.sumOf { it.drawOrderKeyforms.size } + deltaRowsOf(blendLayout?.partRecords)
countInfo[7] = warps.sumOf { it.keyforms.size } + deltaRowsOf(blendLayout?.warpRecords)
countInfo[8] = rotations.sumOf { it.keyforms.size } + deltaRowsOf(blendLayout?.rotationRecords)
countInfo[9] = doc.artMeshes.sumOf { it.keyforms.size } + deltaRowsOf(blendLayout?.meshRecords)
countInfo[10] = positionFloatCount
countInfo[11] = doc.bindings.sumOf { it.axes.size } // total keyform-binding slots
// 12 sizes the runtime's keyform-binding array, which it then indexes by an object's raw
// keyformBindingIndex - so the TABLE WIDTH, matching sections 73/74, not the entry count.
countInfo[12] = context.bindingCount
countInfo[13] = context.totalParamBindings
// 14 counts KEY_POSITIONS' full extent: the main-grid dedup keys, the blend binding key runs,
// and the per-parameter unions (whose counts are section 104). Each term is the same value the
// grid producer wrote, taken from the shared context rather than recomputed.
countInfo[14] = context.mainGridKeyTotal + context.blendLayout.bindingKeys.sumOf { it.size }
if (context.writesUnionRegion) {
countInfo[14] += context.unionKeysByParameter.sumOf { it.size }
}
countInfo[15] = 2 * doc.artMeshes.sumOf { it.vertexCount }
countInfo[16] = doc.artMeshes.sumOf { it.triangleIndices.size }
// 17 sizes MASK_INDEX_DATA, which on MOC3 v6 includes the offscreens' mask prefix (§5.6).
countInfo[17] = doc.artMeshes.sumOf { it.maskDrawableIndices.size } + doc.offscreens.sumOf { it.maskCount }
countInfo[18] = doc.renderOrderGroups.size
countInfo[19] = doc.renderOrderGroups.sumOf { it.children.size }
countInfo[20] = doc.glues.size
countInfo[21] = 2 * doc.glues.sumOf { it.pairs.size }
countInfo[22] = doc.glues.sumOf { it.intensityKeyforms.size }
/**
* Writes CountInfo field [fieldIndex] when the version's block is wide enough.
*
* @param Int fieldIndex The CountInfo word index.
* @param Int value The field value.
*/
fun putField(fieldIndex: Int, value: Int) {
if (fieldIndex < fieldCount) {
countInfo[fieldIndex] = value
}
}
val offscreenKeyformTotal = doc.offscreens.sumOf { it.keyforms.size }
// 23/24: the color tables' actual row count - the moc-6 offscreen keyform prefix, the base
// keyform rows, and the blend delta rows only when the bake carries the delta region. A
// 4.2-era bake counts base + prefix here even though fields 7-9 still include the delta
// rows for the geometry/opacity tables (corpus: Azxiana.moc3, ci23 13957 vs ci7+8+9 13997).
val colorRowTotal =
if (blendLayout != null && !context.hasColorDeltaRows) {
warps.sumOf { it.keyforms.size } + rotations.sumOf { it.keyforms.size } +
doc.artMeshes.sumOf { it.keyforms.size } + offscreenKeyformTotal
} else {
countInfo[7] + countInfo[8] + countInfo[9] + offscreenKeyformTotal
}
if (blendLayout != null || doc.offscreens.isNotEmpty()) {
putField(23, colorRowTotal)
putField(24, colorRowTotal)
}
if (blendLayout != null) {
putField(25, blendLayout.bindingKeys.size)
putField(26, blendLayout.recordsInFileOrder.size)
putField(27, blendLayout.warpRecords.map { it.targetIndex }.distinct().size)
putField(28, blendLayout.meshRecords.map { it.targetIndex }.distinct().size)
putField(29, blendLayout.recordsInFileOrder.sumOf { it.limits.size })
putField(30, blendLayout.pool.size)
putField(31, blendLayout.pool.sumOf { it.keyPositions.size })
putField(32, blendLayout.partRecords.map { it.targetIndex }.distinct().size)
putField(33, blendLayout.rotationRecords.map { it.targetIndex }.distinct().size)
// 34: glue blend shapes - corpus-empty, unmodeled (stays zero).
}
putField(35, doc.offscreens.size)
putField(36, offscreenKeyformTotal)
return intList(countInfo.toList())
}
/**
* Encodes [values] as a packed little-endian `i32[]`.
*
* @param List<Int> values The integers to write.
* @return ByteArray The packed bytes.
*/
private fun intList(values: List<Int>): ByteArray {
val writer = LittleEndianWriter(values.size * 4)
values.forEach(writer::writeInt32)
return writer.toByteArray()
}
@@ -0,0 +1,83 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.model.RotationDeformer
import org.umamo.format.moc3.model.WarpDeformer
/**
* Synthesizes the sections that are a pure function of the object lists: per-object form counts, the
* prefix-sum start columns into the shared static tables, the glue ids, and the constant snap type.
*
* Every value here is redundant with data the document already holds, which is why the decoder
* ignores most of them - but a file that omits or mis-sizes one is not loadable, so a writer has to
* produce them all. Each identity below is corpus-verified by `UnmodeledSectionIdentityProbeTest`.
*
* Only the sections needing NO intermediate from another producer live here. The rest - the
* per-form color refs (137-142), the offscreen-by-part alias (160), the parameter binding/key starts
* (56, 103) - are emitted beside the producer that already computes their inputs, so the two cannot
* drift apart.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
public object MocDerivedIndexes {
/**
* Builds every self-contained derived section for [doc], keyed by section-table index.
*
* @param MocDocument doc The semantic model.
* @return Map Section index → element-region bytes.
*/
public fun derivedIndexSections(doc: MocDocument): Map<Int, ByteArray> {
val sink = SectionSink(doc.version)
/**
* The running prefix sum of [counts]: entry i is the total of everything before it.
*
* @param List counts The per-object run lengths.
* @param Int base The value of entry 0.
* @return List<Int> The start column.
*/
fun prefixSum(counts: List<Int>, base: Int = 0): List<Int> {
var running = base
return counts.map { count ->
val start = running
running += count
start
}
}
// Per-object keyform counts - the run length each object's keyform base points at.
sink.putInts(Section.PART_KEYFORM_COUNT, doc.parts.map { it.drawOrderKeyforms.size })
sink.putInts(Section.WARP_KEYFORM_COUNT, doc.deformers.filterIsInstance<WarpDeformer>().map { it.keyforms.size })
sink.putInts(
Section.ROTATION_KEYFORM_COUNT,
doc.deformers.filterIsInstance<RotationDeformer>().map { it.keyforms.size },
)
// Start columns into the shared static tables. The UV column advances by TWO per vertex
// because section 78 is a flat float array, not a vertex array.
sink.putInts(Section.ARTMESH_UV_START, prefixSum(doc.artMeshes.map { it.vertexCount * 2 }))
sink.putInts(Section.ARTMESH_INDEX_START, prefixSum(doc.artMeshes.map { it.triangleIndices.size }))
// The offscreen masks occupy the PREFIX of section 80 and the drawable masks follow, so the
// drawable column starts past them rather than at zero.
sink.putInts(
Section.ARTMESH_MASK_START,
prefixSum(
doc.artMeshes.map { it.maskDrawableIndices.size },
base = doc.offscreens.sumOf { it.maskIndices.size },
),
)
sink.putInts(Section.RENDER_ORDER_CHILD_START, prefixSum(doc.renderOrderGroups.map { it.children.size }))
// The constant 3 on every parameter of every corpus sample, v1 through v6 - whatever it selects,
// no shipped model ever selects anything else, so there is no model field behind it.
sink.putInts(Section.PARAM_SNAP_TYPE, List(doc.parameters.size) { SNAP_TYPE })
sink.putIds(Section.GLUE_ID, doc.glues.map { it.id })
return sink.toMap()
}
/** The only snap type any corpus model uses; see [Section.PARAM_SNAP_TYPE]. */
private const val SNAP_TYPE: Int = 3
}
@@ -0,0 +1,217 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.io.LittleEndianWriter
import org.umamo.format.moc3.moc.ElementType
import org.umamo.format.moc3.moc.MocModel
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.format.moc3.moc.Section
/**
* Frames an ordered set of section byte-arrays into a valid `.moc3` blob (header + offset table +
* sections), the serializer half of the bake.
*
* Section k is placed at `table[k]`, its start aligned to 64 bytes - or to 4 for an
* identifier-valued section, matching what the editor writes. [bake] carries whatever it cannot
* synthesize from a reference container; [bakeFresh] synthesizes everything and needs none.
* Neither reproduces the editor's byte layout exactly, which is not required for a runtime-valid
* file. The semantic lowering (model → section arrays) is the other half.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §4, §7</a>
*/
public object MocEncoder {
private const val HEADER_SIZE: Int = 64
private val MAGIC: ByteArray = byteArrayOf(0x4D, 0x4F, 0x43, 0x33) // "MOC3"
private const val SECTION_ALIGN: Int = 64
/** Identifier-valued sections align to 4 rather than 64; see [sectionAlignments]. */
private const val ID_SECTION_ALIGN: Int = 4
private const val BUFFER_ALIGN: Int = 64
/**
* Rounds [value] up to the next multiple of [alignment].
*
* @param Int value The value to align.
* @param Int alignment The alignment boundary (e.g. 64).
* @return Int The smallest multiple of [alignment] that is `>= value`.
*/
private fun align(value: Int, alignment: Int): Int = (value + alignment - 1) / alignment * alignment
/**
* Frames [sections] (in table-index order) into a `.moc3` for the given [versionByte].
*
* @param Int versionByte The moc version byte (1..6).
* @param Boolean isBigEndian The endian flag (false for every shipped file).
* @param List sections Section payloads, in table order; section k lands at `table[k]`.
* @return ByteArray The complete `.moc3` bytes.
*/
public fun encode(versionByte: Int, isBigEndian: Boolean, sections: List<ByteArray>): ByteArray {
val sectionTotal = sections.size
// The runtime reads a fixed-size offset table; reserve the editor's region for the version so
// it never reads past the live offsets into section data (0x7C0 for moc <=5, 0x16C0 for moc 6).
val headerRegion = if (versionByte >= 6) 0x16C0 else 0x7C0
require(HEADER_SIZE + sectionTotal * 4 <= headerRegion) {
"offset table ($sectionTotal entries) overruns the $headerRegion-byte header region"
}
val firstOffset = headerRegion
val alignmentByIndex = sectionAlignments(versionByte, sectionTotal)
val offsets = IntArray(sectionTotal)
var cursor = firstOffset
for (sectionIndex in 0 until sectionTotal) {
// A section's START is aligned per ITS OWN rule, so the padding belongs to the section about to
// be placed rather than the one just written. Every section (even an empty one) takes the
// running cursor; the runtime indexes by table slot and tolerates equal offsets for empties.
cursor = align(cursor, alignmentByIndex[sectionIndex])
offsets[sectionIndex] = cursor
cursor += sections[sectionIndex].size
}
val writer = LittleEndianWriter(align(cursor, BUFFER_ALIGN))
writer.writeBytes(MAGIC) // MOC3 header: magic "MOC3" @ +0x00
writer.writeU8(versionByte) // MOC3 header: version @ +0x04
writer.writeU8(if (isBigEndian) 1 else 0) // MOC3 header: endian flag @ +0x05
writer.zeroPad(HEADER_SIZE - writer.position) // reserved @ +0x06
for (offset in offsets) writer.writeInt32(offset) // MOC3 offset table @ +0x40
writer.zeroPad(firstOffset - writer.position) // pad the table region to the data region
for (sectionIndex in 0 until sectionTotal) {
// Pad up to the offset the table already promises for this section.
writer.zeroPad(offsets[sectionIndex] - writer.position)
writer.writeBytes(sections[sectionIndex])
}
writer.alignTo(BUFFER_ALIGN)
return writer.toByteArray()
}
/**
* The start alignment each section index requires, for a given moc version.
*
* Identifier-valued sections align to 4 bytes and everything else to 64. Over-aligning would be
* legal (64 satisfies 4), so this is not a correctness fix - it matches the shape the editor
* writes, which is the standing tie-breaker whenever our convenience and its bytes disagree.
*
* @param Int versionByte The moc version byte.
* @param Int sectionTotal How many table slots to describe.
* @return IntArray The per-index alignment.
*/
private fun sectionAlignments(versionByte: Int, sectionTotal: Int): IntArray {
val alignments = IntArray(sectionTotal) { SECTION_ALIGN }
// An unrecognized version gets the conservative all-64 layout rather than a wrong guess.
val version = MocVersion.entries.firstOrNull { it.byteValue == versionByte } ?: return alignments
for (section in Section.entries) {
if (section.element != ElementType.ID) {
continue
}
val index = section.indexIn(version)
if (index in 0 until sectionTotal) {
alignments[index] = ID_SECTION_ALIGN
}
}
return alignments
}
/**
* Re-frames an existing [MocModel]'s sections into a compact valid `.moc3` (a "repack"). Useful to
* validate the serializer independent of the semantic lowering: the runtime accepts it and reads
* the same model, though the byte layout differs from the original (use
* [org.umamo.format.moc3.moc.MocCodec.write] for a byte-identical re-emit).
*
* @param MocModel model A parsed container.
* @return ByteArray The repacked `.moc3` bytes.
*/
public fun repack(model: MocModel): ByteArray =
encode(model.versionByte, model.isBigEndian, model.sectionBytesInOrder())
/**
* Bakes a (possibly-edited) [doc] to `.moc3` bytes, synthesizing every section [synthesize]'s
* producers cover and carrying anything they do not from [reference]. That carry-through is empty
* for every corpus model (`MocBakeFreshCoverageTest` pins the carried set at nothing), so it stands
* against a section some later format version adds rather than against one we cannot derive. The
* result is runtime-valid; for an unedited document the synthesized sections are byte-exact, so it
* matches the original data.
*
* @param MocModel reference The decoded source providing the carried sections + version.
* @param MocDocument doc The (editable) semantic model to bake.
* @return ByteArray The `.moc3` bytes.
*/
public fun bake(reference: MocModel, doc: MocDocument): ByteArray {
val synthesized = synthesize(doc)
// The reference's table can be SHORTER than the version defines (a stripped or hand-built
// container); pinning the output to it would silently drop synthesized sections past its end.
val tableSize = maxOf(reference.sectionCount, sectionCount(reference.version))
val sections =
List(tableSize) { index ->
synthesized[index] ?: (reference.section(index) ?: ByteArray(0))
}
return encode(reference.versionByte, reference.isBigEndian, sections)
}
/**
* Bakes [doc] with NO reference container: every section is synthesized from the object model.
*
* This is what a document that did not come from a `.moc3` needs - there is nothing to carry from.
* Sections the version does not define are emitted empty.
*
* @param MocVersion version The moc version to emit; must match [doc]'s own.
* @param MocDocument doc The semantic model.
* @param Boolean isBigEndian The endian flag (false for every shipped file).
* @return ByteArray The `.moc3` bytes.
*/
public fun bakeFresh(version: MocVersion, doc: MocDocument, isBigEndian: Boolean = false): ByteArray {
// Loud rather than subtly wrong: lowering a document at a version other than its own would emit
// sections gated for one version with values shaped for another.
require(version == doc.version) { "bakeFresh version $version does not match the document's ${doc.version}" }
val synthesized = synthesize(doc)
val sections = List(sectionCount(version)) { index -> synthesized[index] ?: ByteArray(0) }
return encode(version.byteValue, isBigEndian, sections)
}
/**
* The section indices [bakeFresh] can produce for [doc] - the coverage a completeness gate checks.
*
* An index missing here is one a bake could only carry from a reference container, which is exactly
* what makes a document un-bakeable from scratch.
*
* @param MocDocument doc The semantic model.
* @return Set<Int> The produced section indices.
*/
public fun bakeFreshCoverage(doc: MocDocument): Set<Int> = synthesize(doc).keys
/**
* Every section the lowering can synthesize for [doc], keyed by section-table index.
*
* @param MocDocument doc The semantic model.
* @return Map Section index → element-region bytes.
*/
private fun synthesize(doc: MocDocument): Map<Int, ByteArray> = MocLowering.lower(doc)
/**
* The number of section-table entries the editor emits for a moc [version]. The runtime indexes the
* table by fixed section index and never reads its length, so this only needs to be ≥ the highest
* index used; matching the editor keeps the file shape conventional.
*
* Confirmed against samples for v1 (101), v3 (102), v4 (137), v5 (152), and v6 (167); v2 (102) is
* the one unsampled version and follows the editor's version gates (+1 at 3.3, +35 at 4.2, +15 at 5.0).
*
* Matched exhaustively over [MocVersion] on purpose: with an `else` branch a newly added version
* would silently inherit the previous one's table length, which is a wrong file rather than a
* build error.
*
* @param MocVersion version The moc version.
* @return Int The section count.
*/
public fun sectionCount(version: MocVersion): Int =
when (version) {
MocVersion.V30 -> 101
MocVersion.V33, MocVersion.V40 -> 102
MocVersion.V42 -> 137
MocVersion.V50 -> 152
MocVersion.V53 -> 167
}
}
/**
* The section payloads in table-index order (internal accessor for the encoder). Absent sections
* become empty arrays so the list is dense and index-aligned with the offset table.
*
* @return List<ByteArray> Each section's raw bytes, in table order.
*/
internal fun MocModel.sectionBytesInOrder(): List<ByteArray> = List(sectionCount) { section(it) ?: ByteArray(0) }
@@ -0,0 +1,140 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.format.moc3.moc.ParameterType
import org.umamo.format.moc3.moc.Section
/**
* Synthesizes the keyform-binding grid sections from [context] (byte-exact). Reproduces the
* editor's parameter-binding dedup: a parameter-binding is a unique `(parameter, key positions)`
* pair; they are grouped by owning parameter and, within a parameter, ordered by first occurrence
* scanning keyform-bindings in index order.
*
* @param MocLoweringContext context The shared lowering derivations.
* @return Map Section index → element-region bytes.
*/
internal fun keyformGridSections(context: MocLoweringContext): Map<Int, ByteArray> {
val doc = context.doc
val sink = SectionSink(doc.version)
val version = doc.version
val parameterCount = doc.parameters.size
val bindingCount = context.bindingCount
val bindingAxes = context.bindingAxes
val keySetsByParameter = context.keySetsByParameter
// assign parameter-binding indices grouped by parameter
val parameterBindingIndex = HashMap<Pair<Int, List<Float>>, Int>()
val parameterBindingOrder = ArrayList<List<Float>>()
val parameterBindingCount = IntArray(parameterCount)
for (parameterIndex in 0 until parameterCount) {
parameterBindingCount[parameterIndex] = keySetsByParameter[parameterIndex].size
for (keys in keySetsByParameter[parameterIndex]) {
parameterBindingIndex[parameterIndex to keys] = parameterBindingOrder.size
parameterBindingOrder.add(keys)
}
}
val keyOffset = ArrayList<Int>()
val keyCount = ArrayList<Int>()
val keyPositions = ArrayList<Float>()
for (keys in parameterBindingOrder) {
keyOffset.add(keyPositions.size)
keyCount.add(keys.size)
keyPositions.addAll(keys)
}
val keyformBindingStart = ArrayList<Int>()
val keyformBindingCount = ArrayList<Int>()
val keyformBindingSlot = ArrayList<Int>()
for (bindingIndex in 0 until bindingCount) {
keyformBindingStart.add(keyformBindingSlot.size)
keyformBindingCount.add(bindingAxes[bindingIndex].size)
for ((parameterIndex, keys) in bindingAxes[bindingIndex]) {
keyformBindingSlot.add(parameterBindingIndex.getValue(parameterIndex to keys))
}
}
sink.putInts(Section.PARAMETER_BINDING_COUNT, parameterBindingCount.toList())
// The matching START column, which the runtime uses to find each parameter's binding run. Written
// here rather than beside the other prefix sums because it needs the pool this function builds.
//
// The empty-slot filler is NOT arbitrary: a parameter with no bindings stores -1 when it is NORMAL
// and 0 when it is BLEND_SHAPE. Both values occur within one file (LimeBirb, modelF), so the
// parameter type is the only thing that tells the two fillers apart.
val parameterBindingStart = IntArray(parameterCount)
run {
var cursor = 0
for (parameterIndex in 0 until parameterCount) {
parameterBindingStart[parameterIndex] =
if (parameterBindingCount[parameterIndex] > 0) {
val start = cursor
cursor += parameterBindingCount[parameterIndex]
start
} else if (doc.parameters.getOrNull(parameterIndex)?.type == ParameterType.BLEND_SHAPE) {
0
} else {
-1
}
}
}
sink.putInts(Section.PARAM_BINDING_START, parameterBindingStart.toList())
sink.putInts(Section.BINDING_KEY_OFFSET, keyOffset)
sink.putInts(Section.BINDING_KEY_COUNT, keyCount)
// KEY_POSITIONS is up to THREE regions (MOC3 §5.6): the main-grid dedup keys; then, on a blend
// model, the blend bindings' key runs (section 117 offsets point here); then the per-parameter
// sorted union of main-grid axis keys and blend-binding keys, whose counts are section 104.
// A blend-free document contributes nothing to the middle region and nothing but its main-grid
// keys to the union, so the same walk covers both kinds of document.
//
// Omitting 104 on a v4+ file is not a smaller file, it is an unloadable one: the runtime reads
// it unconditionally to SIZE its parameter key store, and an absent section still resolves to a
// pointer - so it sizes the arena from whatever bytes follow.
val allKeyPositions = ArrayList(keyPositions)
for (bindingKeys in context.blendLayout.bindingKeys) {
bindingKeys.forEach { allKeyPositions.add(it) }
}
val unionBase = allKeyPositions.size
val unionKeyCounts = ArrayList<Int>()
if (context.writesUnionRegion) {
for (unionKeys in context.unionKeysByParameter) {
unionKeyCounts.add(unionKeys.size)
allKeyPositions.addAll(unionKeys)
}
}
sink.putFloats(Section.KEY_POSITIONS, allKeyPositions)
putParameterKeyRuns(sink, version, unionKeyCounts, unionBase)
sink.putInts(Section.KEYFORM_BINDING_SLOT, keyformBindingSlot)
sink.putInts(Section.KEYFORM_BINDING_START, keyformBindingStart)
sink.putInts(Section.KEYFORM_BINDING_COUNT, keyformBindingCount)
return sink.toMap()
}
/**
* Writes the per-parameter key run columns (103 start, 104 count) over the key-position union region.
*
* @param SectionSink sink The calling producer's section sink.
* @param MocVersion version The target version (the columns are MOC3 v4+).
* @param List counts Each parameter's union key count, in parameter order.
* @param Int regionStart Where the union region begins inside KEY_POSITIONS.
*/
private fun putParameterKeyRuns(
sink: SectionSink,
version: MocVersion,
counts: List<Int>,
regionStart: Int,
) {
if (version.byteValue < 4 || counts.isEmpty()) {
return
}
// The start column is an OFFSET INTO KEY_POSITIONS, not a running count from zero: the union
// region sits after the main-grid keys (and, on a blend model, the blend binding keys), so a
// prefix sum based at 0 would point every parameter at the wrong run.
var cursor = regionStart
val starts =
counts.map { count ->
val start = cursor
cursor += count
start
}
sink.putInts(Section.PARAM_KEY_START, starts)
sink.putInts(Section.PARAM_KEY_COUNT, counts)
}
@@ -0,0 +1,68 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.moc.Section
/**
* Lowers a [MocDocument] back to section byte-arrays (the semantic half of the bake).
*
* The work is split across per-concern producers, each in its own file and each mirroring the decoder
* collaborator it has to round-trip against: structure ([structuralSections]), keyform value tables
* ([valueTableSections]), color tables ([colorSections]), the glue/render-order/offscreen tables
* ([auxiliarySections]), the parameter-binding grid ([keyformGridSections]), blend records
* ([blendShapeSections]), the self-contained derived columns ([MocDerivedIndexes]), the zero-filled
* runtime slots ([MocRuntimeSlots]), and section 0 ([countInfoSection]). Everything they share is
* derived once in [MocLoweringContext]; everything they write goes through a [SectionSink].
*
* Every packing here is derived rather than carried, and deterministic, so one document always lowers
* to one set of bytes.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5, §7</a>
*/
public object MocLowering {
/**
* Lowers [doc] to every section it can produce, keyed by section-table index.
*
* The producers are merged STRICTLY: two of them claiming the same index fails here rather than
* resolving by merge order. That is not defensive - a `+` fold would resolve a double claim by
* silently keeping the later producer, leaving the shadowed copy editable with no effect on any
* output and no test to notice. Every index has exactly one owner, and this is what keeps it
* that way.
*
* @param MocDocument doc The semantic model.
* @return Map Section index → element-region bytes (no trailing padding).
*/
public fun lower(doc: MocDocument): Map<Int, ByteArray> {
val context = MocLoweringContext(doc)
val merged = LinkedHashMap<Int, ByteArray>()
val claimedBy = HashMap<Int, String>()
/**
* Folds one producer's output in, failing when it claims an index another producer already owns.
*
* @param String producerName The producer's name, for the failure message.
* @param Map produced Its section index → element-region bytes.
*/
fun merge(producerName: String, produced: Map<Int, ByteArray>) {
for ((index, bytes) in produced) {
val previousProducer = claimedBy.put(index, producerName)
require(previousProducer == null) {
val sectionName = Section.entries.firstOrNull { it.indexIn(doc.version) == index }?.name ?: "unmodeled"
"section $index ($sectionName) claimed by both $previousProducer and $producerName"
}
merged[index] = bytes
}
}
merge("structural", structuralSections(context))
merge("valueTables", valueTableSections(context))
merge("color", colorSections(context))
merge("auxiliary", auxiliarySections(context))
merge("keyformGrid", keyformGridSections(context))
merge("blendShapes", blendShapeSections(context))
merge("runtimeSlots", MocRuntimeSlots.runtimeSlotSections(doc))
merge("derivedIndexes", MocDerivedIndexes.derivedIndexSections(doc))
merge("countInfo", mapOf(Section.COUNT_INFO.indexIn(doc.version) to countInfoSection(context)))
return merged
}
}
@@ -0,0 +1,250 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.format.moc3.moc.ParameterType
import org.umamo.format.moc3.model.BlendShape
import org.umamo.format.moc3.model.BlendShapeKeyform
import org.umamo.format.moc3.model.BlendShapeLimit
import org.umamo.format.moc3.model.BlendShapeTarget
import org.umamo.format.moc3.model.RotationDeformer
import org.umamo.format.moc3.model.WarpDeformer
/**
* Everything the lowering producers derive from a [MocDocument] before any of them writes a byte.
*
* Each producer could rebuild what it needs on its own - the blend-shape file layout, the
* parameter-binding dedup grid, the per-parameter key union - and that would not be merely repeated
* work: CountInfo has to declare the exact extent of tables the other producers write, so two
* traversals drifting apart produces a file whose header disagrees with its own body. Deriving once
* and sharing is what makes them unable to disagree.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
internal class MocLoweringContext(val doc: MocDocument) {
val version: MocVersion = doc.version
val warps: List<WarpDeformer> = doc.deformers.filterIsInstance<WarpDeformer>()
val rotations: List<RotationDeformer> = doc.deformers.filterIsInstance<RotationDeformer>()
/**
* The blend-shape layout, built even when the document has no records.
*
* An empty layout is exactly what a blend-free document has to write (no bindings, no records,
* every per-parameter column at its empty-slot filler), so one code path covers both kinds of
* document instead of two that have to be kept in agreement.
*/
val blendLayout: BlendShapeLayout = BlendShapeLayout(doc)
/** Whether the document carries any blend-shape record at all. */
val hasBlendShapes: Boolean = doc.blendShapes.isNotEmpty()
/** Whether the color tables carry the blend delta region, probed from the records' delta colors. */
val hasColorDeltaRows: Boolean = hasColorDeltaRows(doc)
/**
* The width of the keyform-binding table: one slot per index in `0 until bindingCount`.
*
* Taken from the highest binding index rather than the map's entry count. The two agree on every
* document any producer builds today, but sections 73/74 are written one row per slot while
* CountInfo field 12 sizes the runtime's array, and the runtime indexes that array by an object's
* raw `keyformBindingIndex` - which reaches the highest index, not the entry count. Deriving both
* from this one value is what stops a sparse map from producing a header that under-sizes its body.
*/
val bindingCount: Int = (doc.bindings.maxOfOrNull { it.index } ?: -1) + 1
/** Each keyform binding's axes as `(parameter, key positions)`, in binding-index order. */
val bindingAxes: List<List<Pair<Int, List<Float>>>> =
(0 until bindingCount).map { bindingIndex ->
doc.keyformBinding(bindingIndex)?.axes?.map { it.parameterIndex to it.keyPositions.toList() }
?: emptyList()
}
/** Per parameter, its distinct axis key-lists in first-occurrence order (the main-grid dedup). */
val keySetsByParameter: Array<LinkedHashSet<List<Float>>> =
Array<LinkedHashSet<List<Float>>>(doc.parameters.size) { LinkedHashSet() }.also { keySets ->
for (axes in bindingAxes) {
for ((parameterIndex, keys) in axes) {
keySets[parameterIndex].add(keys)
}
}
}
/** Total distinct parameter-bindings across every parameter (CountInfo field 13). */
val totalParamBindings: Int = keySetsByParameter.sumOf { it.size }
/** Float count of KEY_POSITIONS' main-grid region (the dedup keys, before any later region). */
val mainGridKeyTotal: Int = keySetsByParameter.sumOf { keySet -> keySet.sumOf { it.size } }
/**
* Per parameter, the sorted union of its main-grid axis keys and its blend bindings' keys.
*
* One computation for both kinds of document: on a blend-free one the layout contributes nothing,
* so the union collapses to the main-grid keys.
*/
val unionKeysByParameter: List<List<Float>> =
doc.parameters.indices.map { parameterIndex ->
val unionKeys = mutableSetOf<Float>()
for (keys in keySetsByParameter[parameterIndex]) {
unionKeys.addAll(keys)
}
for (bindingIndex in blendLayout.bindingKeys.indices) {
if (blendLayout.bindingOwnerParameter[bindingIndex] == parameterIndex) {
blendLayout.bindingKeys[bindingIndex].forEach { unionKeys.add(it) }
}
}
unionKeys.sorted()
}
/**
* Whether KEY_POSITIONS carries the per-parameter union region.
*
* On MOC3 v4+ the region is always present and sections 103/104 address it; below v4 it appears
* only in the editor builds that wrote it, which the document records as
* `keyPositionsHasParameterUnion`.
*
* ONE predicate answers both "is the region written" and "does CountInfo field 14 count it",
* because those are the same question: field 14 declares section 77's extent and 103/104 address
* runs inside it, so a document that writes the region without counting it points the runtime past
* the buffer field 14 just sized. Splitting the two would let a v4+ blend-free export declare only
* its main-grid keys while carrying the union region as well.
*/
val writesUnionRegion: Boolean =
hasBlendShapes || doc.keyPositionsHasParameterUnion || version.byteValue >= 4
}
/**
* Whether [doc] carries the color tables' blend delta region. The region is a later format
* addition, absent on 4.2-era bakes whose tables end at the base rows (corpus: Azxiana.moc3,
* V42); the decoder marks absence by null colors on every non-part record keyform, and the
* region is all-or-nothing per file (a present region decodes zeros as non-null Rgb), so any
* non-null delta color means the source carried it.
*
* @param MocDocument doc The semantic model.
* @return Boolean True when the doc's blend keyforms carry color delta rows.
*/
internal fun hasColorDeltaRows(doc: MocDocument): Boolean =
doc.blendShapes.any { blend ->
blend.keyforms.any { keyform ->
when (keyform) {
is BlendShapeKeyform.Warp -> keyform.form.multiplyColor != null
is BlendShapeKeyform.Mesh -> keyform.form.multiplyColor != null
is BlendShapeKeyform.Rotation -> keyform.form.multiplyColor != null
is BlendShapeKeyform.Part -> false
}
}
}
/**
* The blend-shape file layout derived from a document's records: the global record order
* (warp, mesh, part, then rotation records - objects ascending by kind-local index, verified
* on the corpus), the deduplicated binding list (grouped by parameter ascending, first
* occurrence within a parameter), and the deduplicated limit sub-binding pool (sorted by
* gating-parameter index; the within-parameter tie-break is first-occurrence order across
* recordsInFileOrder).
*/
internal class BlendShapeLayout(doc: MocDocument) {
val warpRecords: List<BlendShape>
val meshRecords: List<BlendShape>
val partRecords: List<BlendShape>
val rotationRecords: List<BlendShape>
val recordsInFileOrder: List<BlendShape>
val warpLocalByDeformer: Map<Int, Int>
val rotationLocalByDeformer: Map<Int, Int>
val bindingKeys: List<FloatArray>
val bindingNeutral: IntArray
val bindingOwnerParameter: IntArray
val parameterBegin: IntArray
val parameterBindingCount: IntArray
val bindingIndexOfRecord: IntArray
val pool: List<BlendShapeLimit>
private val poolIndexByValue: Map<List<Any>, Int>
init {
val warpLocal = HashMap<Int, Int>()
val rotationLocal = HashMap<Int, Int>()
var nextWarpLocal = 0
var nextRotationLocal = 0
for ((deformerIndex, deformer) in doc.deformers.withIndex()) {
if (deformer is WarpDeformer) {
warpLocal[deformerIndex] = nextWarpLocal++
} else {
rotationLocal[deformerIndex] = nextRotationLocal++
}
}
warpLocalByDeformer = warpLocal
rotationLocalByDeformer = rotationLocal
warpRecords =
doc.blendShapes.filter { it.target == BlendShapeTarget.WARP }
.sortedBy { warpLocal[it.targetIndex] ?: Int.MAX_VALUE }
meshRecords = doc.blendShapes.filter { it.target == BlendShapeTarget.ART_MESH }.sortedBy { it.targetIndex }
partRecords = doc.blendShapes.filter { it.target == BlendShapeTarget.PART }.sortedBy { it.targetIndex }
rotationRecords =
doc.blendShapes.filter { it.target == BlendShapeTarget.ROTATION }
.sortedBy { rotationLocal[it.targetIndex] ?: Int.MAX_VALUE }
recordsInFileOrder = warpRecords + meshRecords + partRecords + rotationRecords
// Distinct bindings: (parameter, keys, neutral), first-occurrence order re-sorted by
// parameter (stable, so within-parameter order stays first-occurrence).
data class BindingIdentity(val parameterIndex: Int, val keys: List<Float>, val neutralKeyIndex: Int)
val discoveredBindings = LinkedHashSet<BindingIdentity>()
for (record in recordsInFileOrder) {
discoveredBindings.add(
BindingIdentity(record.parameterIndex, record.keyPositions.toList(), record.neutralKeyIndex),
)
}
val orderedBindings = discoveredBindings.toList().sortedBy { it.parameterIndex }
bindingKeys = orderedBindings.map { it.keys.toFloatArray() }
bindingNeutral = IntArray(orderedBindings.size) { bindingIndex -> orderedBindings[bindingIndex].neutralKeyIndex }
bindingOwnerParameter = IntArray(orderedBindings.size) { bindingIndex -> orderedBindings[bindingIndex].parameterIndex }
val bindingIndexByIdentity = orderedBindings.withIndex().associate { (bindingIndex, identity) -> identity to bindingIndex }
bindingIndexOfRecord =
IntArray(recordsInFileOrder.size) { recordIndex ->
val record = recordsInFileOrder[recordIndex]
bindingIndexByIdentity.getValue(
BindingIdentity(record.parameterIndex, record.keyPositions.toList(), record.neutralKeyIndex),
)
}
parameterBegin = IntArray(doc.parameters.size)
parameterBindingCount = IntArray(doc.parameters.size)
var bindingCursor = 0
for (parameterIndex in doc.parameters.indices) {
parameterBindingCount[parameterIndex] =
orderedBindings.count { it.parameterIndex == parameterIndex }
// Binding-less parameters store 0, not the running cumulative - UNLESS the parameter is
// itself blend-shape-typed (a morph-target axis authored with no record bound to it),
// which stores -1 instead.
parameterBegin[parameterIndex] =
when {
parameterBindingCount[parameterIndex] > 0 -> bindingCursor
doc.parameters[parameterIndex].type == ParameterType.BLEND_SHAPE -> -1
else -> 0
}
bindingCursor += parameterBindingCount[parameterIndex]
}
// The limit sub-binding pool, deduplicated by value. Sorted by gating-parameter index
// (corpus-observed); the within-parameter tie-break is first-occurrence order across
// recordsInFileOrder (Kotlin's sortedBy is stable).
fun identityOf(limit: BlendShapeLimit): List<Any> =
listOf(limit.parameterIndex, limit.keyPositions.toList(), limit.weights.toList())
val distinctLimits = LinkedHashMap<List<Any>, BlendShapeLimit>()
for (record in recordsInFileOrder) {
for (limit in record.limits) {
distinctLimits.getOrPut(identityOf(limit)) { limit }
}
}
pool = distinctLimits.values.sortedBy { it.parameterIndex }
poolIndexByValue = pool.withIndex().associate { (poolIndex, poolEntry) -> identityOf(poolEntry) to poolIndex }
}
/**
* The pool index of [limit] (matched by value).
*
* @param BlendShapeLimit limit A per-record expanded limit curve.
* @return Int The deduplicated pool index.
*/
fun poolIndexOf(limit: BlendShapeLimit): Int =
poolIndexByValue.getValue(listOf(limit.parameterIndex, limit.keyPositions.toList(), limit.weights.toList()))
}
@@ -0,0 +1,52 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.moc.ElementType
import org.umamo.format.moc3.moc.Section
/**
* Synthesizes the per-object runtime-slot sections: the 8-byte fields each object block opens with,
* which are all-zero on disk and filled by the runtime after its memory-cast.
*
* These carry no authored data, so a writer only has to SIZE them - but sizing them is not optional.
* The array must be exactly as long as its object list or the runtime reads past the end of the one
* it just allocated, which is why a bake cannot simply carry them from a reference file once the
* object count changes. That is the whole reason they are modeled at all.
*
* Corpus-verified all-zero across every sample by `UnmodeledSectionIdentityProbeTest`.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
public object MocRuntimeSlots {
/**
* Builds every runtime-slot section for [doc], keyed by section-table index.
*
* @param MocDocument doc The semantic model.
* @return Map Section index → zero bytes, sized to the owning object list.
*/
public fun runtimeSlotSections(doc: MocDocument): Map<Int, ByteArray> {
val sink = SectionSink(doc.version)
/**
* Emits one zero-filled slot array, sized to its owning object list.
*
* @param Section section The runtime-slot section.
* @param Int objectCount How many objects the array covers.
*/
fun put(section: Section, objectCount: Int) = sink.putZeros(section, objectCount * ElementType.U64.size)
put(Section.PART_RUNTIME_SLOT, doc.parts.size)
put(Section.DEFORMER_RUNTIME_SLOT, doc.deformers.size)
// The art-mesh block opens with FOUR of them (Lina's research reads them as a header plus three
// unknowns); all four are zero, and all four must be sized.
put(Section.ARTMESH_RUNTIME_SLOT, doc.artMeshes.size)
put(Section.ARTMESH_RUNTIME_SLOT_A, doc.artMeshes.size)
put(Section.ARTMESH_RUNTIME_SLOT_B, doc.artMeshes.size)
put(Section.ARTMESH_RUNTIME_SLOT_C, doc.artMeshes.size)
put(Section.PARAM_RUNTIME_SLOT, doc.parameters.size)
put(Section.PARAM_RUNTIME_SLOT_A, doc.parameters.size)
put(Section.GLUE_RUNTIME_SLOT, doc.glues.size)
put(Section.OFFSCREEN_RUNTIME_SLOT, doc.offscreens.size)
return sink.toMap()
}
}
@@ -0,0 +1,112 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.model.WarpDeformer
/**
* Synthesizes the structural/topology sections from [context], keyed by section-table index.
*
* @param MocLoweringContext context The shared lowering derivations.
* @return Map Section index → element-region bytes (no trailing padding).
*/
internal fun structuralSections(context: MocLoweringContext): Map<Int, ByteArray> {
val doc = context.doc
val sink = SectionSink(doc.version)
doc.canvas?.let { canvas ->
sink.putFloats(Section.CANVAS, canvas.pixelsPerUnit, canvas.originX, canvas.originY, canvas.width, canvas.height, 0f)
}
// parameters
sink.putIds(Section.PARAM_ID, doc.parameters.map { it.id })
sink.putFloats(Section.PARAM_MAX, doc.parameters.map { it.maximumValue })
sink.putFloats(Section.PARAM_MIN, doc.parameters.map { it.minimumValue })
sink.putFloats(Section.PARAM_DEFAULT, doc.parameters.map { it.defaultValue })
sink.putInts(Section.PARAM_REPEAT, doc.parameters.map { if (it.repeats) 1 else 0 })
if (doc.parameters.any { it.type != null }) {
sink.putInts(Section.PARAM_TYPE, doc.parameters.map { it.type!!.number })
}
// parts
sink.putIds(Section.PART_ID, doc.parts.map { it.id })
// MOC3 §5.6 s7/s8: a paired flag column, the same shape as the deformer (s13/s14) and art-mesh
// (s37/s38) pairs. The FIRST carries visibility; the SECOND is 1 on every part of every corpus
// sample and its meaning is unpinned, which `PairedVisibilityFlagProbeTest` pins as an invariant.
// Projecting isVisible into both would put a 0 in a column the editor has never been observed
// writing one into - a hidden part would make our bake the only file in existence that deviates.
sink.putInts(Section.PART_VISIBLE_ARTMESHES, doc.parts.map { if (it.isVisible) 1 else 0 })
sink.putInts(Section.PART_VISIBLE_DEFORMERS, doc.parts.map { 1 })
sink.putInts(Section.PART_PARENT, doc.parts.map { it.parentPartIndex })
sink.putInts(Section.PART_KEYFORM_BINDING, doc.parts.map { it.keyformBindingIndex })
// drawables (art meshes) + topology
sink.putIds(Section.ARTMESH_ID, doc.artMeshes.map { it.id })
sink.putInts(Section.ARTMESH_TEXTURE, doc.artMeshes.map { it.textureIndex })
sink.putBytes(Section.ARTMESH_CONSTANT_FLAGS, ByteArray(doc.artMeshes.size) { doc.artMeshes[it].constantFlags.toByte() })
// MOC3 v6 §5.6 s153: per-drawable packed extended blend (v6-only; the sink drops it below v6).
sink.putInts(Section.ARTMESH_EXTENDED_BLEND, doc.artMeshes.map { it.extendedBlend })
// Hidden art meshes are CARRIED with the flag clear, never dropped - the official editor deletes
// them by default, but Umamo has no option to and doing it silently would be destructive.
sink.putInts(Section.ARTMESH_IS_VISIBLE, doc.artMeshes.map { if (it.isVisible) 1 else 0 })
sink.putInts(Section.ARTMESH_IS_ENABLED, doc.artMeshes.map { if (it.isEnabled) 1 else 0 })
sink.putInts(Section.ARTMESH_VERTEX_COUNT, doc.artMeshes.map { it.vertexCount })
sink.putInts(Section.ARTMESH_INDEX_COUNT, doc.artMeshes.map { it.triangleIndices.size })
sink.putInts(Section.ARTMESH_MASK_COUNT, doc.artMeshes.map { it.maskDrawableIndices.size })
sink.putInts(Section.ARTMESH_PARENT_PART, doc.artMeshes.map { it.parentPartIndex })
sink.putInts(Section.ARTMESH_PARENT_DEFORMER, doc.artMeshes.map { it.parentDeformerIndex })
sink.putInts(Section.ARTMESH_KEYFORM_BINDING, doc.artMeshes.map { it.keyformBindingIndex })
sink.putInts(Section.ARTMESH_KEYFORM_COUNT, doc.artMeshes.map { doc.keyformBinding(it.keyformBindingIndex)?.gridSize ?: 1 })
sink.putFloatConcat(Section.ARTMESH_UV_DATA, doc.artMeshes) { it.vertexUvs }
sink.putShortConcat(Section.ARTMESH_INDEX_DATA, doc.artMeshes) { it.triangleIndices }
// The mask-index block holds (moc 6) the offscreens' mask lists as a PREFIX, then the
// drawables' mask lists (MOC3 §5.6 section 80; s158 offsets from the block start - pinned on
// Model A against the CMO3 clip lists). The prefix synthesizes from the typed
// Offscreen.maskIndices; a doc predating the typed extraction (index count != maskCount)
// carries the section instead.
if (doc.offscreens.all { it.maskIndices.size == it.maskCount }) {
val maskIndexValues = ArrayList<Int>()
for (offscreen in doc.offscreens) {
offscreen.maskIndices.forEach { maskIndexValues.add(it) }
}
for (mesh in doc.artMeshes) {
mesh.maskDrawableIndices.forEach { maskIndexValues.add(it) }
}
sink.putInts(Section.MASK_INDEX_DATA, maskIndexValues)
}
// deformers (unified list + per-type). The block's leading runtime slot is sized by
// [MocRuntimeSlots] along with every other object block's, so it is not written here.
sink.putIds(Section.DEFORMER_ID, doc.deformers.map { it.id })
sink.putInts(Section.DEFORMER_KEYFORM_BINDING, doc.deformers.map { it.keyformBindingIndex })
sink.putInts(Section.DEFORMER_IS_VISIBLE, doc.deformers.map { if (it.isVisible) 1 else 0 })
sink.putInts(Section.DEFORMER_IS_ENABLED, doc.deformers.map { if (it.isEnabled) 1 else 0 })
sink.putInts(Section.DEFORMER_PARENT_PART, doc.deformers.map { it.parentPartIndex })
sink.putInts(Section.DEFORMER_PARENT, doc.deformers.map { it.parentDeformerIndex })
sink.putInts(Section.DEFORMER_TYPE, doc.deformers.map { if (it is WarpDeformer) 0 else 1 })
// per-deformer index within its type group (warps vs rotations), in deformer-list order
val localIndex = IntArray(doc.deformers.size)
run {
var nextWarpLocal = 0
var nextRotationLocal = 0
for ((deformerIndex, deformer) in doc.deformers.withIndex()) {
localIndex[deformerIndex] = if (deformer is WarpDeformer) nextWarpLocal++ else nextRotationLocal++
}
}
sink.putInts(Section.DEFORMER_LOCAL_INDEX, localIndex.toList())
val warps = context.warps
val rotations = context.rotations
sink.putInts(Section.WARP_CONTROL_POINT_COUNT, warps.map { (it.rows + 1) * (it.columns + 1) })
sink.putInts(Section.WARP_ROWS, warps.map { it.rows })
sink.putInts(Section.WARP_COLUMNS, warps.map { it.columns })
sink.putInts(Section.WARP_MODE, warps.map { it.mode })
sink.putInts(Section.WARP_KEYFORM_BINDING, warps.map { it.keyformBindingIndex })
sink.putFloats(Section.ROTATION_BASE_ANGLE, rotations.map { it.baseAngle })
sink.putInts(Section.ROTATION_KEYFORM_BINDING, rotations.map { it.keyformBindingIndex })
// glue topology (mesh pair + binding)
sink.putInts(Section.GLUE_MESH_A, doc.glues.map { it.meshAIndex })
sink.putInts(Section.GLUE_MESH_B, doc.glues.map { it.meshBIndex })
sink.putInts(Section.GLUE_KEYFORM_BINDING, doc.glues.map { it.keyformBindingIndex })
return sink.toMap()
}
@@ -0,0 +1,168 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.io.LittleEndianWriter
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.model.BlendShapeKeyform
/**
* Synthesizes the keyform value tables from [context], keyed by section-table index. These are
* the layout-dependent geometry/scalar tables; the packing is deterministic (warp keyform blocks
* then mesh blocks in `POS_VALUES`, each padded to 16 floats; bases are cumulative), so they
* reconstruct byte-for-byte. The keyform-binding grid (param-binding dedup) is not synthesized
* here.
*
* @param MocLoweringContext context The shared lowering derivations.
* @return Map Section index → element-region bytes.
*/
internal fun valueTableSections(context: MocLoweringContext): Map<Int, ByteArray> {
val doc = context.doc
val sink = SectionSink(doc.version)
val warps = context.warps
val rotations = context.rotations
// POS_VALUES: warp control-point keyform blocks first, then art-mesh vertex keyform blocks,
// each padded to a 16-float (64-byte) boundary. Index tables record each block's float offset.
val positionValues = LittleEndianWriter(64 * 1024)
val warpPositionIndex = ArrayList<Int>()
val warpKeyformBase = IntArray(warps.size)
val warpOpacity = ArrayList<Float>()
for ((warpIndex, warp) in warps.withIndex()) {
warpKeyformBase[warpIndex] = warpPositionIndex.size
for (keyform in warp.keyforms) {
warpPositionIndex.add(positionValues.position / 4)
keyform.controlPoints.forEach(positionValues::writeFloat32)
padTo16Floats(positionValues, keyform.controlPoints.size)
warpOpacity.add(keyform.opacity)
}
}
val meshPositionIndex = ArrayList<Int>()
val meshKeyformBase = IntArray(doc.artMeshes.size)
val meshOpacity = ArrayList<Float>()
val meshDrawOrder = ArrayList<Float>()
for ((meshIndex, mesh) in doc.artMeshes.withIndex()) {
meshKeyformBase[meshIndex] = meshPositionIndex.size
for (keyform in mesh.keyforms) {
meshPositionIndex.add(positionValues.position / 4)
keyform.vertexPositions.forEach(positionValues::writeFloat32)
padTo16Floats(positionValues, keyform.vertexPositions.size)
meshOpacity.add(keyform.opacity)
meshDrawOrder.add(keyform.drawOrder)
}
}
// Blend-shape delta rows append AFTER the base keyforms in the same tables (MOC3 §5.6):
// POS_VALUES gains warp-record then mesh-record delta blocks (16-float padded like the base
// blocks), the per-kind index/scalar tables gain one row per (record, key) in global record
// order, so the per-object bases above stay pure base-prefix indices.
val blendLayout = context.blendLayout.takeIf { context.hasBlendShapes }
if (blendLayout != null) {
for (record in blendLayout.warpRecords) {
for (keyform in record.keyforms) {
val warpDelta = (keyform as? BlendShapeKeyform.Warp)?.form ?: continue
warpPositionIndex.add(positionValues.position / 4)
warpDelta.controlPoints.forEach(positionValues::writeFloat32)
padTo16Floats(positionValues, warpDelta.controlPoints.size)
warpOpacity.add(warpDelta.opacity)
}
}
for (record in blendLayout.meshRecords) {
for (keyform in record.keyforms) {
val meshDelta = (keyform as? BlendShapeKeyform.Mesh)?.form ?: continue
meshPositionIndex.add(positionValues.position / 4)
meshDelta.vertexPositions.forEach(positionValues::writeFloat32)
padTo16Floats(positionValues, meshDelta.vertexPositions.size)
meshOpacity.add(meshDelta.opacity)
meshDrawOrder.add(meshDelta.drawOrder)
}
}
}
sink.putInts(Section.WARP_KEYFORM_BASE, warpKeyformBase.toList())
sink.putInts(Section.ARTMESH_KEYFORM_BASE, meshKeyformBase.toList())
// rotation deformers: per-keyform affine tables, base = cumulative rotation keyforms.
val rotationKeyformBase = IntArray(rotations.size)
val rotationAngle = ArrayList<Float>()
val rotationOriginX = ArrayList<Float>()
val rotationOriginY = ArrayList<Float>()
val rotationScale = ArrayList<Float>()
val rotationReflectX = ArrayList<Int>()
val rotationReflectY = ArrayList<Int>()
val rotationOpacity = ArrayList<Float>()
var rotationKeyformCounter = 0
for ((rotationIndex, rotation) in rotations.withIndex()) {
rotationKeyformBase[rotationIndex] = rotationKeyformCounter
for (keyform in rotation.keyforms) {
rotationAngle.add(keyform.angle)
rotationOriginX.add(keyform.originX)
rotationOriginY.add(keyform.originY)
rotationScale.add(keyform.scale)
rotationReflectX.add(if (keyform.reflectX) 1 else 0)
rotationReflectY.add(if (keyform.reflectY) 1 else 0)
rotationOpacity.add(keyform.opacity)
rotationKeyformCounter++
}
}
sink.putInts(Section.ROTATION_KEYFORM_BASE, rotationKeyformBase.toList())
if (blendLayout != null) {
// MOC3 §5.6: rotation delta rows sit directly in the affine tables 61-67 after the base rows.
for (record in blendLayout.rotationRecords) {
for (keyform in record.keyforms) {
val rotationDelta = (keyform as? BlendShapeKeyform.Rotation)?.form ?: continue
rotationAngle.add(rotationDelta.angle)
rotationOriginX.add(rotationDelta.originX)
rotationOriginY.add(rotationDelta.originY)
rotationScale.add(rotationDelta.scale)
rotationReflectX.add(if (rotationDelta.reflectX) 1 else 0)
rotationReflectY.add(if (rotationDelta.reflectY) 1 else 0)
rotationOpacity.add(rotationDelta.opacity)
}
}
}
sink.putBytes(Section.KEYFORM_POSITION_VALUES, positionValues.toByteArray())
sink.putInts(Section.WARP_KEYFORM_INDEX, warpPositionIndex)
sink.putFloats(Section.WARP_OPACITY, warpOpacity)
sink.putInts(Section.KEYFORM_POSITION_INDEX, meshPositionIndex)
sink.putFloats(Section.ARTMESH_OPACITY, meshOpacity)
sink.putFloats(Section.ARTMESH_DRAW_ORDER, meshDrawOrder)
sink.putFloats(Section.ROTATION_ANGLE, rotationAngle)
sink.putFloats(Section.ROTATION_ORIGIN_X, rotationOriginX)
sink.putFloats(Section.ROTATION_ORIGIN_Y, rotationOriginY)
sink.putFloats(Section.ROTATION_SCALE, rotationScale)
sink.putInts(Section.ROTATION_REFLECT_X, rotationReflectX)
sink.putInts(Section.ROTATION_REFLECT_Y, rotationReflectY)
sink.putFloats(Section.ROTATION_OPACITY, rotationOpacity)
// parts: per-part draw-order keyform table + cumulative base (a static part has a single value).
// MOC3 v5+ §5.6: part-owned blend-shape records append draw-order delta rows to section 58.
val partDrawOrder = ArrayList<Float>()
val partKeyformBase = IntArray(doc.parts.size)
for ((partIndex, part) in doc.parts.withIndex()) {
partKeyformBase[partIndex] = partDrawOrder.size
part.drawOrderKeyforms.forEach { partDrawOrder.add(it) }
}
if (blendLayout != null) {
for (record in blendLayout.partRecords) {
for (keyform in record.keyforms) {
val partDelta = keyform as? BlendShapeKeyform.Part ?: continue
partDrawOrder.add(partDelta.drawOrderDelta)
}
}
}
sink.putInts(Section.PART_KEYFORM_BASE, partKeyformBase.toList())
sink.putFloats(Section.PART_DRAW_ORDER, partDrawOrder)
return sink.toMap()
}
/**
* Zero-pads [writer] so a block of [count] floats reaches the next 16-float (64-byte) boundary.
*
* @param LittleEndianWriter writer The value-table writer to pad.
* @param Int count The number of floats just written in this block.
*/
private fun padTo16Floats(writer: LittleEndianWriter, count: Int) {
val padCount = ((count + 15) / 16 * 16) - count
repeat(padCount) { writer.writeFloat32(0f) }
}
@@ -0,0 +1,180 @@
package org.umamo.format.moc3.encode
import org.umamo.format.moc3.io.LittleEndianWriter
import org.umamo.format.moc3.moc.ElementType
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.moc.Sections
/**
* Collects a lowering producer's output as section index → element-region bytes.
*
* Owns the two things every producer would otherwise repeat: resolving a [Section] to its table index
* for the target version, and skipping a section the version does not define (a negative index). The
* typed putters encode as they store, so a call site names the section and the values and nothing else.
*
* Each typed putter checks the section's declared [ElementType], which is what stops an `i32[]` column
* from being written into an `f32[]` section - the section table is the only record of a section's
* element width, and a mismatch there produces a file the runtime reads at the wrong stride.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
internal class SectionSink(private val version: MocVersion) {
private val sections = LinkedHashMap<Int, ByteArray>()
/**
* The collected sections, keyed by section-table index.
*
* @return Map Section index → element-region bytes.
*/
fun toMap(): Map<Int, ByteArray> = sections
/**
* Stores [bytes] verbatim under [section], if the version defines it.
*
* The unchecked escape hatch: it carries pre-packed blocks (the keyform position values are already
* a little-endian float run) as readily as genuine `u8[]` columns, so it deliberately does not
* check the element type. Prefer a typed putter wherever the values are still typed.
*
* @param Section section The section to write.
* @param ByteArray bytes The element-region bytes.
*/
fun putBytes(section: Section, bytes: ByteArray) {
val index = section.indexIn(version)
if (index >= 0) {
sections[index] = bytes
}
}
/**
* Stores a zero-filled region of [byteCount] bytes under [section].
*
* @param Section section The section to write.
* @param Int byteCount How many zero bytes the region spans.
*/
fun putZeros(section: Section, byteCount: Int): Unit = putBytes(section, ByteArray(byteCount))
/**
* Encodes [values] as a packed little-endian `i32[]` under [section].
*
* @param Section section The section to write.
* @param List<Int> values The integers, in element order.
*/
fun putInts(section: Section, values: List<Int>) {
requireElement(section, ElementType.I32, ElementType.U32)
val writer = LittleEndianWriter(values.size * 4)
values.forEach(writer::writeInt32)
putBytes(section, writer.toByteArray())
}
/**
* Encodes [values] as a packed little-endian `i32[]` under [section].
*
* @param Section section The section to write.
* @param IntArray values The integers, in element order.
*/
fun putInts(section: Section, values: IntArray) {
requireElement(section, ElementType.I32, ElementType.U32)
val writer = LittleEndianWriter(values.size * 4)
values.forEach(writer::writeInt32)
putBytes(section, writer.toByteArray())
}
/**
* Encodes [values] as a packed little-endian `f32[]` under [section].
*
* @param Section section The section to write.
* @param List<Float> values The floats, in element order.
*/
fun putFloats(section: Section, values: List<Float>) {
requireElement(section, ElementType.F32)
val writer = LittleEndianWriter(values.size * 4)
values.forEach(writer::writeFloat32)
putBytes(section, writer.toByteArray())
}
/**
* Encodes [values] as a packed little-endian `f32[]` under [section].
*
* @param Section section The section to write.
* @param Float values The floats, in element order.
*/
fun putFloats(section: Section, vararg values: Float) {
requireElement(section, ElementType.F32)
val writer = LittleEndianWriter(values.size * 4)
values.forEach(writer::writeFloat32)
putBytes(section, writer.toByteArray())
}
/**
* Encodes [values] as a packed little-endian `i16[]` under [section].
*
* @param Section section The section to write.
* @param List<Short> values The shorts, in element order.
*/
fun putShorts(section: Section, values: List<Short>) {
requireElement(section, ElementType.I16)
val writer = LittleEndianWriter(values.size * 2)
values.forEach { shortValue -> writer.writeU16(shortValue.toInt()) }
putBytes(section, writer.toByteArray())
}
/**
* Encodes [identifiers] as fixed [Sections.ID_STRIDE]-byte NUL-terminated, zero-padded id records.
*
* @param Section section The section to write.
* @param List<String> identifiers The identifiers, in element order.
*/
fun putIds(section: Section, identifiers: List<String>) {
requireElement(section, ElementType.ID)
val writer = LittleEndianWriter(identifiers.size * Sections.ID_STRIDE)
for (identifier in identifiers) {
writer.writeFixedString(identifier, Sections.ID_STRIDE)
}
putBytes(section, writer.toByteArray())
}
/**
* Concatenates each item's selected `f32[]` into one packed block under [section].
*
* @param Section section The section to write.
* @param List<T> items The items to draw arrays from.
* @param (T) -> FloatArray select The per-item float array selector.
*/
fun <T> putFloatConcat(section: Section, items: List<T>, select: (T) -> FloatArray) {
requireElement(section, ElementType.F32)
val writer = LittleEndianWriter(items.sumOf { select(it).size } * 4)
for (item in items) {
select(item).forEach(writer::writeFloat32)
}
putBytes(section, writer.toByteArray())
}
/**
* Concatenates each item's selected `i16[]` into one packed block under [section].
*
* @param Section section The section to write.
* @param List<T> items The items to draw arrays from.
* @param (T) -> ShortArray select The per-item short array selector.
*/
fun <T> putShortConcat(section: Section, items: List<T>, select: (T) -> ShortArray) {
requireElement(section, ElementType.I16)
val writer = LittleEndianWriter(items.sumOf { select(it).size } * 2)
for (item in items) {
select(item).forEach { shortValue -> writer.writeU16(shortValue.toInt()) }
}
putBytes(section, writer.toByteArray())
}
/**
* Fails when [section] does not declare one of [allowed] as its element type.
*
* @param Section section The section being written.
* @param ElementType allowed The element types this putter encodes.
*/
private fun requireElement(section: Section, vararg allowed: ElementType) {
require(section.element in allowed) {
"$section is a ${section.element} section; cannot write it as ${allowed.joinToString("/")}"
}
}
}
@@ -0,0 +1,118 @@
package org.umamo.format.moc3.io
/**
* Little-endian, non-obfuscated reader over a byte array.
*
* EN: MOC3 is a flat little-endian blob - no obfuscation, no compression (unlike CMO3's
* big-endian, XOR'd CAFF container). All multi-byte integers and floats are little-endian.
* JA: MOC3 はリトルエンディアンの素のバイナリ(難読化・圧縮なし)。
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md</a>
*/
public class LittleEndianReader(private val data: ByteArray) {
/** Current read cursor, in bytes from the start of [data]. */
public var position: Int = 0
private set
/** Total length of the backing buffer. */
public val size: Int get() = data.size
/**
* Moves the cursor to an absolute byte offset.
*
* @param Int offset Absolute position to seek to.
*/
public fun seek(offset: Int) {
position = offset
}
/**
* Advances the cursor by [count] bytes without interpreting them.
*
* @param Int count Number of bytes to skip.
*/
public fun skip(count: Int) {
position += count
}
/**
* Reads one unsigned byte (0..255).
*
* @return Int The byte value in 0..255.
*/
public fun readU8(): Int {
val value = data[position].toInt() and 0xFF
position += 1
return value
}
/**
* Reads a little-endian unsigned 16-bit integer (0..65535).
*
* @return Int The decoded value.
*/
public fun readU16(): Int {
val low = data[position].toInt() and 0xFF
val high = data[position + 1].toInt() and 0xFF
position += 2
return (high shl 8) or low
}
/**
* Reads a little-endian signed 32-bit integer.
*
* @return Int The decoded value.
*/
public fun readInt32(): Int {
val byte0 = data[position].toInt() and 0xFF
val byte1 = data[position + 1].toInt() and 0xFF
val byte2 = data[position + 2].toInt() and 0xFF
val byte3 = data[position + 3].toInt() and 0xFF
position += 4
return byte0 or (byte1 shl 8) or (byte2 shl 16) or (byte3 shl 24)
}
/**
* Reads a little-endian unsigned 32-bit integer as a [Long] (0..4294967295).
*
* EN: Section offsets and counts are stored as u32; in practice they fit in a signed Int (files
* are < 2 GiB), but this avoids surprises near the boundary.
*
* @return Long The decoded value.
*/
public fun readU32(): Long = readInt32().toLong() and 0xFFFFFFFFL
/**
* Reads a little-endian 32-bit IEEE-754 float.
*
* @return Float The decoded value.
*/
public fun readFloat32(): Float = Float.fromBits(readInt32())
/**
* Reads [count] raw bytes.
*
* @param Int count Number of bytes to read.
* @return ByteArray A freshly allocated copy of the bytes.
*/
public fun readBytes(count: Int): ByteArray {
val out = data.copyOfRange(position, position + count)
position += count
return out
}
/**
* Reads a fixed-width [width]-byte record as a NUL-terminated ASCII/UTF-8 string.
*
* EN: MOC3 IDs are 64-byte records: the identifier bytes, a NUL, then zero padding.
*
* @param Int width Record width in bytes (e.g. 64).
* @return String The string up to the first NUL.
*/
public fun readFixedString(width: Int): String {
val raw = readBytes(width)
var end = 0
while (end < raw.size && raw[end].toInt() != 0) end++
return raw.decodeToString(0, end)
}
}
@@ -0,0 +1,152 @@
package org.umamo.format.moc3.io
/**
* Little-endian, non-obfuscated writer into a growable byte buffer.
*
* EN: Inverse of [LittleEndianReader]; same little-endian conventions, plus [alignTo] for the
* zero-padding MOC3 uses between sections / at end of file.
* JA: [LittleEndianReader] の逆操作。
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md</a>
*/
public class LittleEndianWriter(initialCapacity: Int = 64 * 1024) {
private var buffer = ByteArray(initialCapacity)
/** Number of bytes written so far (also the current write cursor). */
public var position: Int = 0
private set
/**
* Grows the backing buffer if needed so that [additional] more bytes fit from [position].
*
* Doubles capacity (amortised O(1) appends), but jumps straight to the required size when a single
* write exceeds a doubling.
*
* @param Int additional Number of bytes about to be written.
*/
private fun ensure(additional: Int) {
val needed = position + additional
if (needed > buffer.size) {
var newSize = buffer.size * 2
if (newSize < needed) {
newSize = needed
}
buffer = buffer.copyOf(newSize)
}
}
/** Returns a copy of the written bytes (length == [position]). */
public fun toByteArray(): ByteArray = buffer.copyOf(position)
/**
* Writes [count] zero bytes.
*
* @param Int count Number of zero bytes to emit.
*/
public fun zeroPad(count: Int) {
ensure(count)
position += count
}
/**
* Zero-pads until [position] is a multiple of [alignment].
*
* @param Int alignment Byte boundary to align to (e.g. 64).
*/
public fun alignTo(alignment: Int) {
val remainder = position % alignment
if (remainder != 0) {
zeroPad(alignment - remainder)
}
}
/**
* Writes one byte (low 8 bits used).
*
* @param Int value Byte value.
*/
public fun writeU8(value: Int) {
ensure(1)
buffer[position] = value.toByte()
position += 1
}
/**
* Writes a little-endian 16-bit integer (low 16 bits used).
*
* Takes an [Int] and masks rather than taking a [Short] with a range precondition: callers pass
* `shortValue.toInt()`, which sign-extends above 32767, and a mesh with more than 32767 vertices
* writes exactly those values. A `require` here would reject a file the format permits.
*
* @param Int value Value to write; only the low 16 bits are used.
*/
public fun writeU16(value: Int) {
ensure(2)
buffer[position] = value.toByte()
buffer[position + 1] = (value ushr 8).toByte()
position += 2
}
/**
* Writes a little-endian 32-bit integer.
*
* @param Int value Value to write.
*/
public fun writeInt32(value: Int) {
ensure(4)
buffer[position] = value.toByte()
buffer[position + 1] = (value ushr 8).toByte()
buffer[position + 2] = (value ushr 16).toByte()
buffer[position + 3] = (value ushr 24).toByte()
position += 4
}
/**
* Writes a little-endian 32-bit IEEE-754 float.
*
* @param Float value Value to write.
*/
public fun writeFloat32(value: Float): Unit = writeInt32(value.toRawBits())
/**
* Writes raw bytes verbatim.
*
* @param ByteArray bytes Bytes to write.
*/
public fun writeBytes(bytes: ByteArray) {
ensure(bytes.size)
bytes.copyInto(buffer, position)
position += bytes.size
}
/**
* Writes [value] as a fixed-width [width]-byte NUL-terminated record, zero-padded to width.
*
* Inverse of [LittleEndianReader.readFixedString]. MOC3 IDs are 64-byte records holding
* plain ASCII (MOC3 §5.4), so the encoded form must fit in `width - 1` bytes to leave room for
* the terminator; the corpus's longest id is well inside that.
*
* @param String value The identifier to write.
* @param Int width Record width in bytes (e.g. 64).
* @pre The UTF-8 encoding of [value] is shorter than [width].
*/
public fun writeFixedString(value: String, width: Int) {
val encoded = value.encodeToByteArray()
require(encoded.size < width) { "id \"$value\" (${encoded.size} bytes) does not fit a $width-byte record" }
writeBytes(encoded)
zeroPad(width - encoded.size)
}
/**
* Overwrites an already-written little-endian int32 at an absolute offset (back-patching).
*
* @param Int offset Absolute byte offset of the 4-byte slot.
* @param Int value Value to store.
*/
public fun patchInt32(offset: Int, value: Int) {
buffer[offset] = value.toByte()
buffer[offset + 1] = (value ushr 8).toByte()
buffer[offset + 2] = (value ushr 16).toByte()
buffer[offset + 3] = (value ushr 24).toByte()
}
}
@@ -0,0 +1,54 @@
package org.umamo.format.moc3.json
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
/**
* `*.cdi3.json` - display info: human-readable names and grouping for parameters/parts, plus
* 2-axis "combined parameter" hints. Purely cosmetic (no runtime effect).
*
* Keys/order match the `cdi3.json` the editor exports, with one addition: `Drawables` is an Umamo
* extension (MOC3.md §6.3 documents no such key) carrying drawable display names, which the `.moc3`
* itself has no field for. `CombinedParameters` is an array-of-pairs (`[horizontal, vertical]`).
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §cdi3.json</a>
*/
@Serializable
public data class Cdi3Json(
@SerialName("Version") val version: Int,
@SerialName("Parameters") val parameters: List<DisplayParameter>,
@SerialName("ParameterGroups") val parameterGroups: List<DisplayParameterGroup>,
@SerialName("Parts") val parts: List<DisplayPart>,
@SerialName("CombinedParameters") val combinedParameters: List<List<String>>? = null,
@SerialName("Drawables") val drawables: List<DisplayDrawable>? = null,
)
/** A parameter's display name and owning group. */
@Serializable
public data class DisplayParameter(
@SerialName("Id") val id: String,
@SerialName("GroupId") val groupId: String,
@SerialName("Name") val name: String,
)
/** A parameter group's display name and (optional) parent group. */
@Serializable
public data class DisplayParameterGroup(
@SerialName("Id") val id: String,
@SerialName("GroupId") val groupId: String,
@SerialName("Name") val name: String,
)
/** A drawable's display name (the Umamo extension - see [Cdi3Json.drawables]). */
@Serializable
public data class DisplayDrawable(
@SerialName("Id") val id: String,
@SerialName("Name") val name: String,
)
/** A part's display name. */
@Serializable
public data class DisplayPart(
@SerialName("Id") val id: String,
@SerialName("Name") val name: String,
)
@@ -0,0 +1,68 @@
package org.umamo.format.moc3.json
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
/**
* `*.model3.json` - the model manifest referencing the `.moc3`, textures, and other sidecars.
*
* EN: Field order and names match the `model3.json` the editor exports (the SDK's documented
* manifest schema). Optional references are nullable and omitted when absent, so re-emission
* drops nothing.
* JA: モデルマニフェスト。
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §model3.json</a>
*/
@Serializable
public data class Model3Json(
@SerialName("Version") val version: Int,
@SerialName("FileReferences") val fileReferences: FileReferences,
@SerialName("Groups") val groups: List<Model3Group>? = null,
@SerialName("HitAreas") val hitAreas: List<Model3HitArea>? = null,
)
/** File references within a [Model3Json]; all but [moc]/[textures] are optional. */
@Serializable
public data class FileReferences(
@SerialName("Moc") val moc: String,
@SerialName("Textures") val textures: List<String>,
@SerialName("Pose") val pose: String? = null,
@SerialName("Physics") val physics: String? = null,
@SerialName("UserData") val userData: String? = null,
@SerialName("DisplayInfo") val displayInfo: String? = null,
@SerialName("Expressions") val expressions: List<Model3Expression>? = null,
@SerialName("Motions") val motions: Map<String, List<Model3Motion>>? = null,
)
/** An auto-wiring group (e.g. `EyeBlink`, `LipSync`) of parameter or part IDs. */
@Serializable
public data class Model3Group(
@SerialName("Target") val target: String,
@SerialName("Name") val name: String,
@SerialName("Ids") val ids: List<String>,
)
/** A hit-test area mapping a display name to a drawable ID. */
@Serializable
public data class Model3HitArea(
@SerialName("Name") val name: String,
@SerialName("Id") val id: String,
)
/** An expression reference (`*.exp3.json`) with optional fade times. */
@Serializable
public data class Model3Expression(
@SerialName("Name") val name: String,
@SerialName("File") val file: String,
@SerialName("FadeInTime") val fadeInTime: kotlinx.serialization.json.JsonPrimitive? = null,
@SerialName("FadeOutTime") val fadeOutTime: kotlinx.serialization.json.JsonPrimitive? = null,
)
/** A motion reference (`*.motion3.json`) within a named group, with optional sound and fade times. */
@Serializable
public data class Model3Motion(
@SerialName("File") val file: String,
@SerialName("Sound") val sound: String? = null,
@SerialName("FadeInTime") val fadeInTime: kotlinx.serialization.json.JsonPrimitive? = null,
@SerialName("FadeOutTime") val fadeOutTime: kotlinx.serialization.json.JsonPrimitive? = null,
)
@@ -0,0 +1,117 @@
package org.umamo.format.moc3.json
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.JsonPrimitive
/**
* `*.physics3.json` - the physics rig definition (input/output bindings, particle chains).
*
* EN: Physical quantities (weights, scales, positions, forces, normalization bounds) are kept as
* [JsonPrimitive] so the editor's exact numeric tokens round-trip (it prints integral floats
* without a trailing `.0`). The physics math is out of scope here; this only models the file.
* JA: 物理演算リグ定義。数値はトークン保持。
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §physics3.json</a>
*/
@Serializable
public data class Physics3Json(
@SerialName("Version") val version: Int,
@SerialName("Meta") val meta: PhysicsMeta,
@SerialName("PhysicsSettings") val physicsSettings: List<PhysicsSetting>,
)
/** Counts, effective forces, optional fps, and the names dictionary for a [Physics3Json]. */
@Serializable
public data class PhysicsMeta(
@SerialName("PhysicsSettingCount") val physicsSettingCount: Int,
@SerialName("TotalInputCount") val totalInputCount: Int,
@SerialName("TotalOutputCount") val totalOutputCount: Int,
@SerialName("VertexCount") val vertexCount: Int,
@SerialName("Fps") val fps: JsonPrimitive? = null,
@SerialName("EffectiveForces") val effectiveForces: EffectiveForces,
@SerialName("PhysicsDictionary") val physicsDictionary: List<PhysicsDictionaryEntry>,
)
/** The constant gravity and wind vectors. */
@Serializable
public data class EffectiveForces(
@SerialName("Gravity") val gravity: PhysicsVector2,
@SerialName("Wind") val wind: PhysicsVector2,
)
/** A 2D vector with token-preserving components. */
@Serializable
public data class PhysicsVector2(
@SerialName("X") val x: JsonPrimitive,
@SerialName("Y") val y: JsonPrimitive,
)
/** A `(Id, Name)` pair naming a physics setting (parallel to [Physics3Json.physicsSettings] by index). */
@Serializable
public data class PhysicsDictionaryEntry(
@SerialName("Id") val id: String,
@SerialName("Name") val name: String,
)
/** One physics setting: its inputs, outputs, particle chain, and normalization. */
@Serializable
public data class PhysicsSetting(
@SerialName("Id") val id: String,
@SerialName("Input") val input: List<PhysicsInput>,
@SerialName("Output") val output: List<PhysicsOutput>,
@SerialName("Vertices") val vertices: List<PhysicsVertex>,
@SerialName("Normalization") val normalization: PhysicsNormalization,
)
/** A parameter-driven input to the rig. */
@Serializable
public data class PhysicsInput(
@SerialName("Source") val source: PhysicsTarget,
@SerialName("Weight") val weight: JsonPrimitive,
@SerialName("Type") val type: String,
@SerialName("Reflect") val reflect: Boolean,
)
/** A particle-driven output to a parameter. */
@Serializable
public data class PhysicsOutput(
@SerialName("Destination") val destination: PhysicsTarget,
@SerialName("VertexIndex") val vertexIndex: Int,
@SerialName("Scale") val scale: JsonPrimitive,
@SerialName("Weight") val weight: JsonPrimitive,
@SerialName("Type") val type: String,
@SerialName("Reflect") val reflect: Boolean,
)
/** A target reference (`Target` kind + `Id`). */
@Serializable
public data class PhysicsTarget(
@SerialName("Target") val target: String,
@SerialName("Id") val id: String,
)
/** A particle in the chain (`[0]` is the anchor). */
@Serializable
public data class PhysicsVertex(
@SerialName("Position") val position: PhysicsVector2,
@SerialName("Mobility") val mobility: JsonPrimitive,
@SerialName("Delay") val delay: JsonPrimitive,
@SerialName("Acceleration") val acceleration: JsonPrimitive,
@SerialName("Radius") val radius: JsonPrimitive,
)
/** Input normalization ranges for position and angle. */
@Serializable
public data class PhysicsNormalization(
@SerialName("Position") val position: PhysicsNormalizationRange,
@SerialName("Angle") val angle: PhysicsNormalizationRange,
)
/** A `(Minimum, Default, Maximum)` normalization range. */
@Serializable
public data class PhysicsNormalizationRange(
@SerialName("Minimum") val minimum: JsonPrimitive,
@SerialName("Default") val default: JsonPrimitive,
@SerialName("Maximum") val maximum: JsonPrimitive,
)
@@ -0,0 +1,30 @@
package org.umamo.format.moc3.json
import kotlinx.serialization.ExperimentalSerializationApi
import kotlinx.serialization.json.Json
/**
* The `Json` configuration that reproduces the Cubism editor's sidecar output.
*
* Tab-indented, pretty-printed, properties in declaration order; optional fields are omitted
* when absent (`explicitNulls = false`). Numeric leaves the editor prints without a trailing
* `.0` (e.g. `"Y": -1`, `"Weight": 60`) are modelled as
* [kotlinx.serialization.json.JsonPrimitive] so the original token round-trips exactly.
* Decoding tolerates unknown keys (`ignoreUnknownKeys`): newer Cubism exports add manifest
* fields the schema does not model yet (e.g. Cubism 5's FileReferences.MotionSync), and a
* reader that rejects them refuses valid real-world models. The flag affects decoding only,
* so encoded output is unchanged - but it means decode-then-encode DROPS unmodelled keys, so
* a future sidecar re-emit path must preserve unknown keys explicitly (raw JsonObject
* passthrough) rather than relying on the serializer.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §JSON sidecars</a>
*/
@OptIn(ExperimentalSerializationApi::class)
internal val SidecarJson: Json =
Json {
prettyPrint = true
prettyPrintIndent = "\t"
explicitNulls = false
encodeDefaults = true
ignoreUnknownKeys = true
}
@@ -0,0 +1,35 @@
package org.umamo.format.moc3.json
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
/**
* `*.userdata3.json` - per-object user strings attached to drawables.
*
* EN: Keys/order match the `userdata3.json` the editor exports (`Meta` is `UserDataCount` +
* `TotalUserDataSize`; the SDK only consumes `Target == "ArtMesh"` entries).
* JA: ユーザーデータ。
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §userdata3.json</a>
*/
@Serializable
public data class UserData3Json(
@SerialName("Version") val version: Int,
@SerialName("Meta") val meta: UserDataMeta,
@SerialName("UserData") val userData: List<UserDataEntry>,
)
/** Counts for a [UserData3Json]: number of entries and total byte size of their values. */
@Serializable
public data class UserDataMeta(
@SerialName("UserDataCount") val userDataCount: Int,
@SerialName("TotalUserDataSize") val totalUserDataSize: Int,
)
/** A single user-data entry: target kind, target ID, and the user string. */
@Serializable
public data class UserDataEntry(
@SerialName("Target") val target: String,
@SerialName("Id") val id: String,
@SerialName("Value") val value: String,
)
@@ -0,0 +1,61 @@
package org.umamo.format.moc3.moc
/**
* Per-drawable constant flags (`SEC_DRAW_CFLAG`, section index 42), a `u8` bitmask. These match the
* public runtime API (`csmConstantDrawableFlags`); the low bits are blend mode, then masking.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md</a>
*/
public object ConstantFlag {
/** Additive blending. */
public const val BLEND_ADDITIVE: Int = 1 shl 0
/** Multiplicative blending. */
public const val BLEND_MULTIPLICATIVE: Int = 1 shl 1
/** The mesh is double-sided. */
public const val IS_DOUBLE_SIDED: Int = 1 shl 2
/** The clipping mask is inverted. */
public const val IS_INVERTED_MASK: Int = 1 shl 3
}
/**
* Per-drawable dynamic flags (`csmDynamicDrawableFlags`), a `u8` bitmask of per-frame state. Not
* stored in the file (computed by the runtime), recorded here for completeness of the public model.
*/
public object DynamicFlag {
public const val IS_VISIBLE: Int = 1 shl 0
public const val VISIBILITY_DID_CHANGE: Int = 1 shl 1
public const val OPACITY_DID_CHANGE: Int = 1 shl 2
public const val DRAW_ORDER_DID_CHANGE: Int = 1 shl 3
public const val RENDER_ORDER_DID_CHANGE: Int = 1 shl 4
public const val VERTEX_POSITIONS_DID_CHANGE: Int = 1 shl 5
public const val BLEND_COLOR_DID_CHANGE: Int = 1 shl 6
}
/**
* Parameter kind (`SEC_PARAM_TYPE`, section index 114; present from MOC3 v4 / `Parameter.Types`).
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md</a>
*/
public enum class ParameterType(public val number: Int) {
/** A normal scalar parameter. */
NORMAL(0),
/** A blend-shape parameter (drives additive keyform deltas). */
BLEND_SHAPE(1),
;
public companion object {
/**
* Resolves a stored type number to a [ParameterType].
*
* @param Int number The i32 type code.
* @return ParameterType The matching kind.
*/
public fun fromNumber(number: Int): ParameterType =
entries.firstOrNull { it.number == number }
?: throw IllegalArgumentException("unknown parameter type: $number")
}
}
@@ -0,0 +1,91 @@
package org.umamo.format.moc3.moc
import org.umamo.format.moc3.io.LittleEndianReader
import org.umamo.format.moc3.io.LittleEndianWriter
/**
* Reads and writes the `.moc3` binary container.
*
* A `.moc3` is a 64-byte header, a section-offset table at `0x40`, then the sections the table
* points at (each 16-byte-or-coarser aligned, the data region beginning at
* [Sections.DATA_SECTION_BEGIN]). The exporter appends sections sequentially and pads the file
* to a multiple of 64, so the sections partition `[firstOffset, EOF)` in table order. We keep
* every section verbatim, so [write] reproduces an unedited file byte-for-byte.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md</a>
*/
public object MocCodec {
private const val HEADER_SIZE: Int = 64
private val MAGIC: ByteArray = byteArrayOf(0x4D, 0x4F, 0x43, 0x33) // "MOC3"
/**
* True if [bytes] starts with the `MOC3` magic and is at least header-sized.
*
* @param ByteArray bytes Candidate file contents.
* @return Boolean Whether this looks like a `.moc3`.
*/
public fun isMoc3(bytes: ByteArray): Boolean =
// MOC3 header: magic "MOC3" @ +0x00
bytes.size >= HEADER_SIZE && bytes[0] == MAGIC[0] && bytes[1] == MAGIC[1] && bytes[2] == MAGIC[2] && bytes[3] == MAGIC[3]
/**
* Parses a `.moc3` from raw bytes.
*
* @param ByteArray bytes The file contents.
* @return MocModel The parsed header, offset table, and section bytes.
* @throws IllegalArgumentException if the magic, version, or structure is invalid.
*/
public fun read(bytes: ByteArray): MocModel {
require(isMoc3(bytes)) { "Not a moc3: bad magic or too small" }
val versionByte = bytes[4].toInt() and 0xFF // MOC3 header: version @ +0x04
require(versionByte in 1..MocVersion.LATEST) { "Unsupported moc3 version byte: $versionByte" }
// MOC3 offset table @ +0x40: dense run of u32 file offsets, terminated by zero padding.
// (Editor output never has interior zero offsets; a 0 marks the start of the pad to the data
// region.)
val reader = LittleEndianReader(bytes)
reader.seek(0x40)
val offsets = ArrayList<Int>()
while (reader.position + 4 <= bytes.size) {
val value = reader.readU32()
if (value == 0L) {
break
}
offsets.add(value.toInt())
}
require(offsets.isNotEmpty()) { "moc3 has no sections" }
val sectionCount = offsets.size
val sections =
Array(sectionCount) { sectionIndex ->
val start = offsets[sectionIndex]
val end = if (sectionIndex + 1 < sectionCount) offsets[sectionIndex + 1] else bytes.size
require(start in HEADER_SIZE..bytes.size && end in start..bytes.size) {
"section $sectionIndex offset out of range: [$start, $end) in ${bytes.size}"
}
bytes.copyOfRange(start, end)
}
return MocModel(bytes.copyOfRange(0, HEADER_SIZE), offsets.toIntArray(), sections)
}
/**
* Serializes a [MocModel] back to `.moc3` bytes.
* Byte-identical to the source for an unedited model.
*
* @param MocModel model The model to write.
* @return ByteArray The complete `.moc3` file bytes.
*/
public fun write(model: MocModel): ByteArray {
val firstOffset = model.offsets[0]
val tableEnd = HEADER_SIZE + model.offsets.size * 4
require(firstOffset >= tableEnd) { "Offset table ($tableEnd B) overruns the first section ($firstOffset)" }
val total = firstOffset + model.rawSections.sumOf { it.size }
val writer = LittleEndianWriter(total)
writer.writeBytes(model.header) // 64-byte header (magic, version, endian flag, reserved)
for (offset in model.offsets) writer.writeInt32(offset)
writer.zeroPad(firstOffset - writer.position) // pad header+table region up to the data region
for (section in model.rawSections) writer.writeBytes(section)
return writer.toByteArray()
}
}
@@ -0,0 +1,232 @@
package org.umamo.format.moc3.moc
import org.umamo.format.moc3.io.LittleEndianReader
/** Canvas dimensions and origin (section [Section.CANVAS], `f32[6]`). Pixel units. */
public data class CanvasInfo(
val pixelsPerUnit: Float,
val originX: Float,
val originY: Float,
val width: Float,
val height: Float,
)
/**
* A model parameter (slider). [type] is null on MOC3 versions without `Parameter.Types` (< 4).
* [repeats] is the Cubism 5.3+ "Parameter repeat flags" (section 54): true wraps the value into
* `[minimumValue, maximumValue)` instead of clamping.
*/
public data class MocParameter(
val id: String,
val minimumValue: Float,
val maximumValue: Float,
val defaultValue: Float,
val type: ParameterType?,
val repeats: Boolean = false,
)
/** A part (visibility/draw-order group). [parentPartIndex] is -1 when the part is at the root. */
public data class MocPart(
val id: String,
val parentPartIndex: Int,
)
/** A drawable (ArtMesh). [constantFlags] is the [ConstantFlag] bitmask. */
public data class MocDrawable(
val id: String,
val textureIndex: Int,
val constantFlags: Int,
val vertexCount: Int,
val indexCount: Int,
val maskCount: Int,
val parentPartIndex: Int,
)
/**
* A parsed `.moc3`: the 64-byte header, the section-offset table, and each section's raw bytes.
*
* The model retains every section verbatim (the slice `[offset[k], offset[k+1])`, last → EOF,
* including padding) so [org.umamo.format.moc3.moc.MocCodec.write] reproduces an unedited file
* byte identical. A handful of structural sections (counts, canvas, IDs, parameters, parts,
* drawables) are exposed here as typed accessors for callers that need only the shape of a model;
* every section, deformation payload included, is reachable typed through [sections].
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md</a>
*/
public class MocModel internal constructor(
/** The 64-byte file header `[0, 0x40)`, preserved verbatim. */
public val header: ByteArray,
/** Absolute file offset of each section, in table order (length == section count). */
public val offsets: IntArray,
/** Raw bytes of each section, in table order; section k == original `[offsets[k], offsets[k+1])`. */
internal val rawSections: Array<ByteArray>,
) {
/** Typed Layer-1 access to the deformation sections (deformers, keyforms, glue, colors, …). */
public val sections: MocSections by lazy { MocSections(this) }
/** The raw version byte at offset 0x04. */
public val versionByte: Int get() = header[4].toInt() and 0xFF // MOC3 header: version @ +0x04
/** The typed format version. */
public val version: MocVersion get() = MocVersion.fromByte(versionByte)
/** Whether the file declares big-endian byte order (offset 0x05); false for every shipped file. */
public val isBigEndian: Boolean get() = header[5].toInt() != 0 // MOC3 header: endian flag @ +0x05
/** Number of sections present in the offset table. */
public val sectionCount: Int get() = offsets.size
/**
* Returns the raw bytes of section [index] (including its trailing padding), or null if absent.
*
* @param Int index A section-table index (a [Section]'s [Section.indexIn] for this version).
* @return ByteArray? The section bytes, or null when the section is not present.
*/
public fun section(index: Int): ByteArray? = rawSections.getOrNull(index)
/**
* The CountInfo block (section 0) decoded as a `u32[]` (indexable with `Sections.CI_*`).
*
* Read by raw index rather than through [sections], because every `PER_*` sizing rule in
* [MocSections] reads THIS - routing it back through the typed accessor would be circular.
*/
public val countInfo: IntArray by lazy {
val raw = section(Section.COUNT_INFO.indexIn(version)) ?: return@lazy IntArray(0)
val reader = LittleEndianReader(raw)
IntArray(raw.size / 4) { reader.readInt32() }
}
/**
* Reads one count from the CountInfo block, defaulting to 0 when the index is absent.
*
* @param Int index A `Sections.CI_*` field index into [countInfo].
* @return Int The count, or 0 when out of range.
*/
private fun count(index: Int): Int = countInfo.getOrElse(index) { 0 }
/** Number of parts. */
public val partCount: Int get() = count(Sections.CI_PARTS)
/** Number of drawables (ArtMeshes). */
public val drawableCount: Int get() = count(Sections.CI_DRAWABLES)
/** Number of parameters. */
public val parameterCount: Int get() = count(Sections.CI_PARAMETERS)
/** Number of deformers (warp + rotation). */
public val deformerCount: Int get() = count(Sections.CI_DEFORMERS)
/** Number of glue (affecter) entries. */
public val glueCount: Int get() = count(Sections.CI_GLUES)
/** The canvas dimensions/origin, or null if the canvas section is absent. */
public val canvasInfo: CanvasInfo? by lazy {
// The file stores f32[6]; the sixth is a trailing zero the model does not carry.
val values = sections.floatArray(Section.CANVAS)
if (values.size < 5) {
return@lazy null
}
CanvasInfo(
pixelsPerUnit = values[0],
originX = values[1],
originY = values[2],
width = values[3],
height = values[4],
)
}
// The three accessors below pad a short or absent section out to [elementCount] rather than
// returning what the file happens to hold. The callers index positionally by object, so a
// stripped or truncated section must read as zeros/blanks instead of throwing - the same
// defensive contract MocDecoder relies on for the object blocks' common heads.
/**
* Reads [section] as a packed `i32[elementCount]`, zero-filling anything the file omits.
*
* @param Section section An I32 section.
* @param Int elementCount Number of 32-bit integers the caller will index.
* @return IntArray The decoded values (length == [elementCount]).
*/
private fun ints(section: Section, elementCount: Int): IntArray {
val decoded = sections.intArray(section)
return if (decoded.size == elementCount) decoded else decoded.copyOf(elementCount)
}
/**
* Reads [section] as a packed `f32[elementCount]`, zero-filling anything the file omits.
*
* @param Section section An F32 section.
* @param Int elementCount Number of 32-bit floats the caller will index.
* @return FloatArray The decoded values (length == [elementCount]).
*/
private fun floats(section: Section, elementCount: Int): FloatArray {
val decoded = sections.floatArray(section)
return if (decoded.size == elementCount) decoded else decoded.copyOf(elementCount)
}
/**
* Reads [section] as [elementCount] fixed-width ID records, blank-filling anything the file omits.
*
* @param Section section An ID section.
* @param Int elementCount Number of ID records the caller will index.
* @return List<String> The decoded IDs (length == [elementCount]).
*/
private fun idStrings(section: Section, elementCount: Int): List<String> {
val decoded = sections.idArray(section)
return if (decoded.size == elementCount) decoded else List(elementCount) { decoded.getOrElse(it) { "" } }
}
/** The parameters, in file order. */
public fun parameters(): List<MocParameter> {
val parameterCount = parameterCount
val ids = idStrings(Section.PARAM_ID, parameterCount)
val maxima = floats(Section.PARAM_MAX, parameterCount)
val minima = floats(Section.PARAM_MIN, parameterCount)
val defaults = floats(Section.PARAM_DEFAULT, parameterCount)
val repeats = ints(Section.PARAM_REPEAT, parameterCount)
// Absent before moc 4, so a null types array means "every parameter is normal".
val types = if (sections.isPresent(Section.PARAM_TYPE)) ints(Section.PARAM_TYPE, parameterCount) else null
return List(parameterCount) { parameterIndex ->
MocParameter(
ids[parameterIndex],
minima[parameterIndex],
maxima[parameterIndex],
defaults[parameterIndex],
types?.let { ParameterType.fromNumber(it[parameterIndex]) },
repeats[parameterIndex] != 0,
)
}
}
/** The parts, in file order. */
public fun parts(): List<MocPart> {
val partCount = partCount
val ids = idStrings(Section.PART_ID, partCount)
val parents = ints(Section.PART_PARENT, partCount)
return List(partCount) { partIndex -> MocPart(ids[partIndex], parents[partIndex]) }
}
/** The drawables (ArtMeshes), in file order. */
public fun drawables(): List<MocDrawable> {
val drawableCount = drawableCount
val ids = idStrings(Section.ARTMESH_ID, drawableCount)
val textures = ints(Section.ARTMESH_TEXTURE, drawableCount)
val vertexCounts = ints(Section.ARTMESH_VERTEX_COUNT, drawableCount)
val indexCounts = ints(Section.ARTMESH_INDEX_COUNT, drawableCount)
val maskCounts = ints(Section.ARTMESH_MASK_COUNT, drawableCount)
val parents = ints(Section.ARTMESH_PARENT_PART, drawableCount)
// One byte per drawable, not an i32; byteArray already pads to the drawable count.
val flagsRaw = sections.byteArray(Section.ARTMESH_CONSTANT_FLAGS)
return List(drawableCount) { drawableIndex ->
MocDrawable(
id = ids[drawableIndex],
textureIndex = textures[drawableIndex],
constantFlags = (flagsRaw.getOrNull(drawableIndex)?.toInt() ?: 0) and 0xFF,
vertexCount = vertexCounts[drawableIndex],
indexCount = indexCounts[drawableIndex],
maskCount = maskCounts[drawableIndex],
parentPartIndex = parents[drawableIndex],
)
}
}
}
@@ -0,0 +1,198 @@
package org.umamo.format.moc3.moc
import org.umamo.format.moc3.io.LittleEndianReader
import org.umamo.format.moc3.io.LittleEndianWriter
/**
* Typed read access to every [Section] of a [MocModel] (the "Layer-1" view): each section as a flat
* array of its element type, sized per its [Sizing] rule.
*
* Per-object sections (`PER_*`) are read for their CountInfo count, capped at what the slice holds
* (see [elementCount]); `TABLE` sections are read across the whole section slice (lossless -
* trailing padding becomes trailing zero elements the semantic layer never dereferences). Reading
* is non-destructive; the container's byte-identical write is unaffected.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md</a>
*/
public class MocSections internal constructor(private val model: MocModel) {
private val version: MocVersion = model.version
/**
* The element count for a section with the given [sizing] rule (its CountInfo field), or -1 for a
* [Sizing.TABLE] section (whose count comes from the slice size, not CountInfo).
*
* @param Sizing sizing The section's sizing rule.
* @return Int The per-object count, or -1 for table sections.
*/
private fun count(sizing: Sizing): Int =
when (sizing) {
Sizing.PER_PART -> ci(Sections.CI_PARTS)
Sizing.PER_DEFORMER -> ci(Sections.CI_DEFORMERS)
Sizing.PER_WARP -> ci(Sections.CI_WARPS)
Sizing.PER_ROTATION -> ci(Sections.CI_ROTATIONS)
Sizing.PER_DRAWABLE -> ci(Sections.CI_DRAWABLES)
Sizing.PER_PARAMETER -> ci(Sections.CI_PARAMETERS)
Sizing.PER_GLUE -> ci(Sections.CI_GLUES)
Sizing.PER_RENDER_ORDER_GROUP -> ci(Sections.CI_RENDER_ORDER_GROUPS)
Sizing.PER_RENDER_ORDER_CHILD -> ci(Sections.CI_RENDER_ORDER_CHILDREN)
Sizing.PER_OFFSCREEN -> ci(Sections.CI_OFFSCREENS)
Sizing.PER_BLENDSHAPE_WARP -> ci(Sections.CI_BLENDSHAPE_WARPS)
Sizing.PER_BLENDSHAPE_MESH -> ci(Sections.CI_BLENDSHAPE_MESHES)
Sizing.PER_BLENDSHAPE_ROTATION -> ci(Sections.CI_BLENDSHAPE_ROTATIONS)
Sizing.PER_BLENDSHAPE_PART -> ci(Sections.CI_BLENDSHAPE_PARTS)
Sizing.PER_BLENDSHAPE_GLUE -> ci(Sections.CI_BLENDSHAPE_GLUES)
Sizing.PER_PART_FORM -> ci(Sections.CI_PART_FORMS)
Sizing.PER_WARP_FORM -> ci(Sections.CI_WARP_FORMS)
Sizing.PER_ROTATION_FORM -> ci(Sections.CI_ROTATION_FORMS)
Sizing.PER_ARTMESH_FORM -> ci(Sections.CI_ARTMESH_FORMS)
Sizing.PER_OFFSCREEN_FORM -> ci(Sections.CI_OFFSCREEN_KEYFORMS)
Sizing.TABLE -> -1
}
/**
* Reads CountInfo field [index], defaulting to 0 when absent.
*
* @param Int index A `Sections.CI_*` CountInfo field index.
* @return Int The count, or 0 when out of range.
*/
private fun ci(index: Int): Int = model.countInfo.getOrElse(index) { 0 }
/**
* The raw section slice backing [section] for this model's version, or null when the section is
* absent (version-gated out) or empty.
*
* @param Section section The section to locate.
* @return ByteArray? The section bytes, or null.
*/
private fun rawSlice(section: Section): ByteArray? {
val index = section.indexIn(version)
if (index < 0) {
return null
}
// A zero-length section carries no data; treat it as absent so PER_* reads don't run past it
// (a bake emits empty slots for sections it omits, e.g. blend shapes on a stripped model).
return model.section(index)?.takeIf { it.isNotEmpty() }
}
/** Whether [section] is present in this model's version and has a section slice. */
public fun isPresent(section: Section): Boolean = rawSlice(section) != null
/**
* Number of elements [section] decodes to (CountInfo count, or whole-slice count for tables).
*
* A per-object count is clamped to what the slice can actually hold. CountInfo and the
* section bytes are independent on disk, so a stripped or truncated file can claim more
* objects than it stores; reading the claim would run off the end of the slice and fail the
* whole decode, which [org.umamo.format.moc3.decode.MocDecoder] promises not to do for an
* absent or partial id/flag section. Clamping yields a short array instead, which every
* caller already tolerates (they index through `getOrElse`).
*
* @param Section section The section to size.
* @return Int The element count, 0 when the section is absent.
*/
public fun elementCount(section: Section): Int {
val slice = rawSlice(section) ?: return 0
val sliceCapacity = slice.size / section.element.size
return if (section.sizing == Sizing.TABLE) sliceCapacity else minOf(count(section.sizing), sliceCapacity)
}
/**
* Reads [section] as an [IntArray] (for I32/U32 sections).
*
* @param Section section A section whose element type is I32 or U32.
* @return IntArray The decoded values (empty if the section is absent).
*/
public fun intArray(section: Section): IntArray {
require(section.element == ElementType.I32 || section.element == ElementType.U32) { "$section is not an int section" }
val slice = rawSlice(section) ?: return IntArray(0)
val reader = LittleEndianReader(slice)
return IntArray(elementCount(section)) { reader.readInt32() }
}
/**
* Reads [section] as a [FloatArray] (for F32 sections).
*
* @param Section section A section whose element type is F32.
* @return FloatArray The decoded values (empty if the section is absent).
*/
public fun floatArray(section: Section): FloatArray {
require(section.element == ElementType.F32) { "$section is not a float section" }
val slice = rawSlice(section) ?: return FloatArray(0)
val reader = LittleEndianReader(slice)
return FloatArray(elementCount(section)) { reader.readFloat32() }
}
/**
* Reads [section] as a [ShortArray] (for I16 sections, e.g. glue vertex indices).
*
* @param Section section A section whose element type is I16.
* @return ShortArray The decoded values (empty if the section is absent).
*/
public fun shortArray(section: Section): ShortArray {
require(section.element == ElementType.I16) { "$section is not an i16 section" }
val slice = rawSlice(section) ?: return ShortArray(0)
val reader = LittleEndianReader(slice)
return ShortArray(elementCount(section)) { reader.readU16().toShort() }
}
/**
* Reads [section] as a [ByteArray] (for U8 sections, e.g. flag bytes).
*
* @param Section section A section whose element type is U8.
* @return ByteArray The decoded bytes (empty if the section is absent).
*/
public fun byteArray(section: Section): ByteArray {
require(section.element == ElementType.U8) { "$section is not a u8 section" }
val slice = rawSlice(section) ?: return ByteArray(0)
return slice.copyOf(elementCount(section))
}
/**
* Reads [section] as fixed-width ID records (for ID sections, e.g. deformer ids).
*
* @param Section section A section whose element type is ID.
* @return List<String> The decoded identifiers (empty if the section is absent).
*/
public fun idArray(section: Section): List<String> {
require(section.element == ElementType.ID) { "$section is not an id section" }
val slice = rawSlice(section) ?: return emptyList()
val reader = LittleEndianReader(slice)
// One source of truth for the record width: ElementType.ID.size IS the id stride, and sizing the
// walk from anything else lets the two drift and silently misread every id after the first.
return List(elementCount(section)) { reader.readFixedString(section.element.size) }
}
/**
* Re-serializes [section]'s element region (the real elements, excluding trailing padding).
* Used to validate that the typed decode is lossless against the original bytes.
*
* @param Section section The section to re-encode.
* @return ByteArray The element-region bytes.
*/
public fun reencodeElementRegion(section: Section): ByteArray {
val elementCount = elementCount(section)
val writer = LittleEndianWriter(elementCount * section.element.size + 8)
when (section.element) {
ElementType.I32, ElementType.U32 -> intArray(section).forEach(writer::writeInt32)
ElementType.F32 -> floatArray(section).forEach(writer::writeFloat32)
ElementType.I16 -> shortArray(section).forEach { shortValue -> writer.writeU16(shortValue.toInt()) }
ElementType.U8 -> writer.writeBytes(byteArray(section))
// Re-encoded from the decoded strings, so this genuinely exercises the id-record walk and the
// NUL-terminate-then-zero-pad convention rather than comparing raw bytes to themselves. Every
// id record in the corpus pads cleanly with zeros after its terminator, which is what makes the
// round trip byte-exact; a file that padded with garbage would fail here, and should.
ElementType.ID ->
idArray(section).forEach { identifier ->
writer.writeFixedString(identifier, section.element.size)
}
// A runtime slot is opaque (zero on disk, filled after the memory-cast), so there is no typed
// decode to re-serialize from and its element region round-trips as raw bytes.
ElementType.U64 -> writer.writeBytes(rawElementRegion(section))
}
return writer.toByteArray()
}
/** The element-region bytes straight from the file (first `elementCount × element.size` bytes). */
public fun rawElementRegion(section: Section): ByteArray =
rawSlice(section)?.copyOf(elementCount(section) * section.element.size) ?: ByteArray(0)
}
@@ -0,0 +1,59 @@
package org.umamo.format.moc3.moc
import org.umamo.format.FormatVersion
/**
* The `.moc3` format version, stored as a single byte at file offset `0x04`.
*
* The byte (1..6) gates which sections are present; each value corresponds to a Cubism editor
* release. Newer versions only add sections at higher table indices, so a reader for a high
* version transparently reads lower ones.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §version gating</a>
*/
public enum class MocVersion(public val byteValue: Int, public val editorRange: String) : FormatVersion {
/** MOC3 v1 - Cubism 3.0-3.2 (base section set). */
V30(1, "3.0-3.2"),
/** MOC3 v2 - Cubism 3.3. */
V33(2, "3.3"),
/** MOC3 v3 - Cubism 4.0. */
V40(3, "4.0"),
/** MOC3 v4 - Cubism 4.2 (+ warp/rotation deformer color, `Parameter.Types`, art-mesh/warp blend shapes). */
V42(4, "4.2"),
/** MOC3 v5 - Cubism 5.0 (+ per-form color rows; blend shapes on parts and rotation deformers). */
V50(5, "5.0"),
/** MOC3 v6 - Cubism 5.3 (+ offscreen rendering). */
V53(6, "5.3"),
;
/** Short token combining the version byte and the editor releases that write it. */
override val label: String get() = "moc3 v$byteValue / Cubism $editorRange"
/**
* Human-readable support summary.
*
* @return String The summary sentence.
*/
override fun describe(): String = "Supported: $label"
public companion object {
/** The highest version byte understood here (matches the runtime core's latest). */
public const val LATEST: Int = 6
/**
* Resolves a raw version byte to a [MocVersion].
*
* @param Int byte The version byte from file offset 0x04.
* @return MocVersion The matching version.
* @throws IllegalArgumentException if the byte is outside 1..6.
*/
public fun fromByte(byte: Int): MocVersion =
entries.firstOrNull { it.byteValue == byte }
?: throw IllegalArgumentException("unsupported moc3 version byte: $byte")
}
}
@@ -0,0 +1,527 @@
package org.umamo.format.moc3.moc
/** Element width of a section's array. */
public enum class ElementType(public val size: Int) {
/** unsigned 8-bit (flag bytes). */
U8(1),
/** signed 16-bit (glue vertex indices). */
I16(2),
/** signed 32-bit. */
I32(4),
/** unsigned 32-bit (CountInfo). */
U32(4),
/** unsigned 64-bit (the per-object runtime slots, zero on disk). */
U64(8),
/** IEEE-754 32-bit float. */
F32(4),
/** fixed 64-byte NUL-terminated ID record. */
ID(64),
}
/**
* How a section's element count is determined.
*
* Per-object arrays are sized by a CountInfo count; "table" arrays (keyform values, key
* positions, glue pairs, …) have no single count field and are read across the whole section
* slice (the runtime indexes them via base/offset tables, not a length). Reading the full slice
* is lossless - trailing zero padding becomes trailing zero elements that the semantic layer
* never dereferences.
*/
public enum class Sizing {
PER_PART,
PER_DEFORMER,
PER_WARP,
PER_ROTATION,
PER_DRAWABLE,
PER_PARAMETER,
PER_GLUE,
PER_RENDER_ORDER_GROUP,
PER_RENDER_ORDER_CHILD,
PER_OFFSCREEN,
PER_BLENDSHAPE_WARP,
PER_BLENDSHAPE_MESH,
PER_BLENDSHAPE_ROTATION,
PER_BLENDSHAPE_PART,
PER_BLENDSHAPE_GLUE,
// One entry per KEYFORM of the object kind, not per object: the flat form arrays each object
// indexes into through its keyform base. Sized by CountInfo 6-9 and 36 respectively.
PER_PART_FORM,
PER_WARP_FORM,
PER_ROTATION_FORM,
PER_ARTMESH_FORM,
PER_OFFSCREEN_FORM,
/** Read across the whole section slice (a table indexed elsewhere). */
TABLE,
}
/**
* EVERY section of a `.moc3`, with its element type, sizing rule, and section-table index per moc
* version - the single registry the decoder, the lowering, and the lossless gate all read.
*
* The per-version indices are on-disk facts (which table slot holds which data, recovered from the
* runtime). `index[version-1]` gives the slot; `-1` means the section is absent in that version.
*
* Completeness is enforced, not aspirational: `SectionRegistryTest` asserts that every slot each
* version's table defines has exactly one entry here, that no two entries claim a slot, and that an
* index never moves once introduced. That matters because a section modeled nowhere can only be
* carried verbatim from a reference container - which is precisely what stops a document being baked
* from scratch.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §section map</a>
*/
public enum class Section(
public val element: ElementType,
public val sizing: Sizing,
private vararg val indexByVersion: Int, // [v1,v2,v3,v4,v5,v6]; -1 = absent
) {
// --- global ---
/** The object-count array itself (section 0); every `PER_*` sizing rule reads its fields. */
COUNT_INFO(ElementType.U32, Sizing.TABLE, 0, 0, 0, 0, 0, 0),
/** Canvas `f32[6]`: pixels-per-unit, origin x/y, width, height, and a trailing zero. */
CANVAS(ElementType.F32, Sizing.TABLE, 1, 1, 1, 1, 1, 1),
// --- deformers (unified list) ---
/**
* Per-deformer 8-byte runtime slot, the block's leading field. Zero in every corpus file (the
* runtime fills it after the memory-cast), so it carries no authored data - it is modeled only so
* a bake sizes it to the deformer count instead of carrying a stale array from the source file.
* Every object block opens with the same slot: parts 2, art meshes 29, parameters 49, glues 89,
* offscreens 154. All are corpus-verified all-zero (UnmodeledSectionIdentityProbeTest).
*/
DEFORMER_RUNTIME_SLOT(ElementType.U64, Sizing.PER_DEFORMER, 10, 10, 10, 10, 10, 10),
/** Per-deformer authored id (e.g. "Warp349", "B_LEG_01"), unique within the model. */
DEFORMER_ID(ElementType.ID, Sizing.PER_DEFORMER, 11, 11, 11, 11, 11, 11),
/**
* Per-deformer keyform-binding index, in unified deformer order. Duplicates the per-type
* [WARP_KEYFORM_BINDING] / [ROTATION_KEYFORM_BINDING] value for the same deformer (corpus-verified
* identical); both are written because the runtime addresses each by a different path.
*/
DEFORMER_KEYFORM_BINDING(ElementType.I32, Sizing.PER_DEFORMER, 12, 12, 12, 12, 12, 12),
/**
* Per-deformer visibility flag (`0`/`1`), the editor's eye toggle. The only deformer flag that
* ever deviates from 1 on the corpus. See [DEFORMER_IS_ENABLED] for the pairing caveat.
*/
DEFORMER_IS_VISIBLE(ElementType.I32, Sizing.PER_DEFORMER, 13, 13, 13, 13, 13, 13),
/**
* Per-deformer second flag, `1` on every deformer of every corpus model - so it is not the
* visibility toggle; [DEFORMER_IS_VISIBLE] is.
*
* That split is an inference rather than a join result. The art-mesh pair (37/38) has the same
* shape and WAS pinned by joining miku_verycursed against its CMO3 twin, and the only deformer
* deviation anywhere (Azxiana, 7 of 623) sits in the first column exactly as the art-mesh
* deviations do - but Azxiana has no twin, so nothing proves it directly.
*/
DEFORMER_IS_ENABLED(ElementType.I32, Sizing.PER_DEFORMER, 14, 14, 14, 14, 14, 14),
/** Per-deformer owning part (the organizational tree), -1 at the root. */
DEFORMER_PARENT_PART(ElementType.I32, Sizing.PER_DEFORMER, 15, 15, 15, 15, 15, 15),
DEFORMER_PARENT(ElementType.I32, Sizing.PER_DEFORMER, 16, 16, 16, 16, 16, 16),
DEFORMER_TYPE(ElementType.I32, Sizing.PER_DEFORMER, 17, 17, 17, 17, 17, 17),
/** Per-deformer 0-based index within its type group (warps vs rotations), in deformer-list order. */
DEFORMER_LOCAL_INDEX(ElementType.I32, Sizing.PER_DEFORMER, 18, 18, 18, 18, 18, 18),
// --- warp deformers ---
WARP_KEYFORM_BINDING(ElementType.I32, Sizing.PER_WARP, 19, 19, 19, 19, 19, 19),
WARP_KEYFORM_BASE(ElementType.I32, Sizing.PER_WARP, 20, 20, 20, 20, 20, 20),
/** Per-warp keyform count (its binding's grid size); the run length starting at [WARP_KEYFORM_BASE]. */
WARP_KEYFORM_COUNT(ElementType.I32, Sizing.PER_WARP, 21, 21, 21, 21, 21, 21),
/** Per-warp control-point count `(rows+1)·(columns+1)` (the runtime validates it against rows/cols). */
WARP_CONTROL_POINT_COUNT(ElementType.I32, Sizing.PER_WARP, 22, 22, 22, 22, 22, 22),
WARP_ROWS(ElementType.I32, Sizing.PER_WARP, 23, 23, 23, 23, 23, 23),
WARP_COLUMNS(ElementType.I32, Sizing.PER_WARP, 24, 24, 24, 24, 24, 24),
/**
* Warp interpolation mode (0 = triangle split, non-zero = bilinear quad).
*
* Gated from MOC3 v2 (Cubism 3.3), which is where slot 101 first exists at all -
* [org.umamo.format.moc3.encode.MocEncoder.sectionCount] gives v1 101 slots and v2 102. A v3 gate
* would leave v2's slot 101 modeled by nothing, which
* `SectionRegistryTest.everyTableSlotIsModeledForEveryVersion` rejects. UNVERIFIED against a
* sample: the corpus has no v2 file (v1, v3, v4, v5, v6 only), so this rests on the two agreeing
* sources rather than on bytes. Harmless if wrong - an absent section reads as absent.
*/
WARP_MODE(ElementType.I32, Sizing.PER_WARP, -1, 101, 101, 101, 101, 101),
WARP_COLOR_BASE(ElementType.I32, Sizing.PER_WARP, -1, -1, -1, 105, 105, 105),
WARP_OPACITY(ElementType.F32, Sizing.TABLE, 59, 59, 59, 59, 59, 59),
/** Keyform → packed-position offset table for warps/rotations (distinct from art meshes' [KEYFORM_POSITION_INDEX]). */
WARP_KEYFORM_INDEX(ElementType.I32, Sizing.TABLE, 60, 60, 60, 60, 60, 60),
/**
* Per-warp-keyform multiply / screen color row refs (moc 5+), each `colorBase[warp] + gridIndex`.
* The two arrays are BIT-IDENTICAL on every corpus sample, the same shape the offscreen keyform
* rows (162/163) have - so both are derivable and neither carries independent data.
*/
WARP_FORM_MULTIPLY_ROW(ElementType.I32, Sizing.PER_WARP_FORM, -1, -1, -1, -1, 137, 137),
WARP_FORM_SCREEN_ROW(ElementType.I32, Sizing.PER_WARP_FORM, -1, -1, -1, -1, 138, 138),
// --- rotation deformers ---
ROTATION_KEYFORM_BINDING(ElementType.I32, Sizing.PER_ROTATION, 25, 25, 25, 25, 25, 25),
ROTATION_KEYFORM_BASE(ElementType.I32, Sizing.PER_ROTATION, 26, 26, 26, 26, 26, 26),
/** Per-rotation keyform count (its binding's grid size). */
ROTATION_KEYFORM_COUNT(ElementType.I32, Sizing.PER_ROTATION, 27, 27, 27, 27, 27, 27),
/** Per-rotation-keyform color row refs (moc 5+); see [WARP_FORM_MULTIPLY_ROW]. */
ROTATION_FORM_MULTIPLY_ROW(ElementType.I32, Sizing.PER_ROTATION_FORM, -1, -1, -1, -1, 139, 139),
ROTATION_FORM_SCREEN_ROW(ElementType.I32, Sizing.PER_ROTATION_FORM, -1, -1, -1, -1, 140, 140),
ROTATION_COLOR_BASE(ElementType.I32, Sizing.PER_ROTATION, -1, -1, -1, 106, 106, 106),
ROTATION_BASE_ANGLE(ElementType.F32, Sizing.PER_ROTATION, 28, 28, 28, 28, 28, 28),
ROTATION_OPACITY(ElementType.F32, Sizing.TABLE, 61, 61, 61, 61, 61, 61),
ROTATION_ANGLE(ElementType.F32, Sizing.TABLE, 62, 62, 62, 62, 62, 62),
ROTATION_ORIGIN_X(ElementType.F32, Sizing.TABLE, 63, 63, 63, 63, 63, 63),
ROTATION_ORIGIN_Y(ElementType.F32, Sizing.TABLE, 64, 64, 64, 64, 64, 64),
ROTATION_SCALE(ElementType.F32, Sizing.TABLE, 65, 65, 65, 65, 65, 65),
ROTATION_REFLECT_X(ElementType.I32, Sizing.TABLE, 66, 66, 66, 66, 66, 66),
ROTATION_REFLECT_Y(ElementType.I32, Sizing.TABLE, 67, 67, 67, 67, 67, 67),
// --- art meshes ---
/**
* The art-mesh block's four leading 8-byte runtime slots (all-zero on disk, like every other
* object block's). Lina's research marks these header and unknown A, B, and C.
*/
ARTMESH_RUNTIME_SLOT(ElementType.U64, Sizing.PER_DRAWABLE, 29, 29, 29, 29, 29, 29),
ARTMESH_RUNTIME_SLOT_A(ElementType.U64, Sizing.PER_DRAWABLE, 30, 30, 30, 30, 30, 30),
ARTMESH_RUNTIME_SLOT_B(ElementType.U64, Sizing.PER_DRAWABLE, 31, 31, 31, 31, 31, 31),
ARTMESH_RUNTIME_SLOT_C(ElementType.U64, Sizing.PER_DRAWABLE, 32, 32, 32, 32, 32, 32),
/** Per-drawable authored id, e.g. "ArtMesh42" or "D_HAIR_BACK_00". */
ARTMESH_ID(ElementType.ID, Sizing.PER_DRAWABLE, 33, 33, 33, 33, 33, 33),
/**
* Per-drawable visibility flag (`0`/`1`) - the editor's eye toggle, PROVEN by joining
* miku_verycursed against its CMO3 twin: it exports its hidden art meshes rather than dropping
* them, and exactly its 3 hidden meshes carry `0` here. See [ARTMESH_IS_ENABLED] for the pairing.
*/
ARTMESH_IS_VISIBLE(ElementType.I32, Sizing.PER_DRAWABLE, 37, 37, 37, 37, 37, 37),
/**
* Per-drawable second flag, `1` on every drawable of every corpus sample - so whatever it means, it
* is not the visibility toggle ([ARTMESH_IS_VISIBLE] is). Lina's research indicates that this is
* the visibility flag, but probing indicates that it is not.
*/
ARTMESH_IS_ENABLED(ElementType.I32, Sizing.PER_DRAWABLE, 38, 38, 38, 38, 38, 38),
/** Per-drawable owning part (the organizational tree), -1 at the root. */
ARTMESH_PARENT_PART(ElementType.I32, Sizing.PER_DRAWABLE, 39, 39, 39, 39, 39, 39),
/** Per-drawable texture (atlas page) index. */
ARTMESH_TEXTURE(ElementType.I32, Sizing.PER_DRAWABLE, 41, 41, 41, 41, 41, 41),
/**
* Per-drawable render-config bitmask - ONE BYTE per drawable, not an i32. Carries the legacy
* 2-bit blend mode, the double-sided bit, and the invert-mask bit; see
* [org.umamo.format.moc3.moc.ConstantFlag].
*/
ARTMESH_CONSTANT_FLAGS(ElementType.U8, Sizing.PER_DRAWABLE, 42, 42, 42, 42, 42, 42),
ARTMESH_VERTEX_COUNT(ElementType.I32, Sizing.PER_DRAWABLE, 43, 43, 43, 43, 43, 43),
/** Per-drawable start into the UV float table (section 78): the prefix sum of 2 x vertex count. */
ARTMESH_UV_START(ElementType.I32, Sizing.PER_DRAWABLE, 44, 44, 44, 44, 44, 44),
ARTMESH_INDEX_COUNT(ElementType.I32, Sizing.PER_DRAWABLE, 46, 46, 46, 46, 46, 46),
ARTMESH_MASK_COUNT(ElementType.I32, Sizing.PER_DRAWABLE, 48, 48, 48, 48, 48, 48),
/** Per-drawable start into the triangle-index table (section 79): the prefix sum of index count. */
ARTMESH_INDEX_START(ElementType.I32, Sizing.PER_DRAWABLE, 45, 45, 45, 45, 45, 45),
/**
* Per-drawable start into the mask-index table (section 80): the prefix sum of mask count, BASED at
* the offscreen mask block that precedes the drawable masks, so entry 0 is not generally zero.
*/
ARTMESH_MASK_START(ElementType.I32, Sizing.PER_DRAWABLE, 47, 47, 47, 47, 47, 47),
/** Per-art-mesh-keyform color row refs (moc 5+); see [WARP_FORM_MULTIPLY_ROW]. */
ARTMESH_FORM_MULTIPLY_ROW(ElementType.I32, Sizing.PER_ARTMESH_FORM, -1, -1, -1, -1, 141, 141),
ARTMESH_FORM_SCREEN_ROW(ElementType.I32, Sizing.PER_ARTMESH_FORM, -1, -1, -1, -1, 142, 142),
// --- art-mesh deformation refs ---
ARTMESH_KEYFORM_BINDING(ElementType.I32, Sizing.PER_DRAWABLE, 34, 34, 34, 34, 34, 34),
ARTMESH_KEYFORM_BASE(ElementType.I32, Sizing.PER_DRAWABLE, 35, 35, 35, 35, 35, 35),
/** Per-drawable keyform count (its keyform-binding grid size). */
ARTMESH_KEYFORM_COUNT(ElementType.I32, Sizing.PER_DRAWABLE, 36, 36, 36, 36, 36, 36),
ARTMESH_COLOR_BASE(ElementType.I32, Sizing.PER_DRAWABLE, -1, -1, -1, 107, 107, 107),
ARTMESH_PARENT_DEFORMER(ElementType.I32, Sizing.PER_DRAWABLE, 40, 40, 40, 40, 40, 40),
ARTMESH_OPACITY(ElementType.F32, Sizing.TABLE, 68, 68, 68, 68, 68, 68),
ARTMESH_DRAW_ORDER(ElementType.F32, Sizing.TABLE, 69, 69, 69, 69, 69, 69),
/**
* Per-drawable packed extended blend, colorMode | (alphaMode shl 8) - the 5.3 blend surface
* (color 0-17, alpha 0-4, same encoding as [OFFSCREEN_BLEND_MODE]). 0 = legacy blend, which
* stays in the constant-flags 2-bit field. MOC3 v6 §5.6 s153; pinned by the PartClipping bake
* (authored Screen/Out drawable stored 522 = 10 or (2 shl 8)).
*/
ARTMESH_EXTENDED_BLEND(ElementType.I32, Sizing.PER_DRAWABLE, -1, -1, -1, -1, -1, 153),
// --- shared static geometry tables ---
/** All drawables' UVs, concatenated as interleaved `u,v`; each indexes in at [ARTMESH_UV_START]. */
ARTMESH_UV_DATA(ElementType.F32, Sizing.TABLE, 78, 78, 78, 78, 78, 78),
/** All drawables' triangle indices (`u16`), concatenated; each starts at [ARTMESH_INDEX_START]. */
ARTMESH_INDEX_DATA(ElementType.I16, Sizing.TABLE, 79, 79, 79, 79, 79, 79),
/**
* Clipping mask references. The OFFSCREEN masks form the prefix of this table and the drawable
* masks follow, which is why [ARTMESH_MASK_START] is based rather than starting at zero.
*/
MASK_INDEX_DATA(ElementType.I32, Sizing.TABLE, 80, 80, 80, 80, 80, 80),
// --- shared keyform value tables ---
KEYFORM_POSITION_INDEX(ElementType.I32, Sizing.TABLE, 70, 70, 70, 70, 70, 70),
KEYFORM_POSITION_VALUES(ElementType.F32, Sizing.TABLE, 71, 71, 71, 71, 71, 71),
// --- parameters ---
/** The parameter block's leading 8-byte runtime slot; all-zero on disk, sized only. */
PARAM_RUNTIME_SLOT(ElementType.U64, Sizing.PER_PARAMETER, 49, 49, 49, 49, 49, 49),
/** Per-parameter authored id, e.g. "ParamAngleX" - a format-level identifier, never localized. */
PARAM_ID(ElementType.ID, Sizing.PER_PARAMETER, 50, 50, 50, 50, 50, 50),
// NB: the file stores MAX before MIN.
PARAM_MAX(ElementType.F32, Sizing.PER_PARAMETER, 51, 51, 51, 51, 51, 51),
PARAM_MIN(ElementType.F32, Sizing.PER_PARAMETER, 52, 52, 52, 52, 52, 52),
PARAM_DEFAULT(ElementType.F32, Sizing.PER_PARAMETER, 53, 53, 53, 53, 53, 53),
/** Per-parameter repeat flag: true wraps the value into `[min, max)` instead of clamping. */
PARAM_REPEAT(ElementType.I32, Sizing.PER_PARAMETER, 54, 54, 54, 54, 54, 54),
/**
* Per-parameter snap type. The constant `3` on every parameter of every corpus sample, v1 through
* v6, so it needs no model field - a writer emits 3.
*/
PARAM_SNAP_TYPE(ElementType.I32, Sizing.PER_PARAMETER, 55, 55, 55, 55, 55, 55),
/**
* Per-parameter start into the binding-set pool: the running prefix sum of
* [PARAMETER_BINDING_COUNT] over parameters that HAVE bindings. A parameter with none stores
* `-1` when it is NORMAL and `0` when it is BLEND_SHAPE (`Parameter.Types`, section 114) - both
* values occur in one file, and only the parameter type separates them.
*/
PARAM_BINDING_START(ElementType.I32, Sizing.PER_PARAMETER, 56, 56, 56, 56, 56, 56),
/** Per-parameter second 8-byte runtime slot (moc 4+); all-zero on disk, sized only. */
PARAM_RUNTIME_SLOT_A(ElementType.U64, Sizing.PER_PARAMETER, -1, -1, -1, 102, 102, 102),
/**
* Per-parameter start into the key-position table (moc 4+): the prefix sum of the per-parameter
* key count (section 104), BASED at the end of the preceding key region rather than at zero.
*/
PARAM_KEY_START(ElementType.I32, Sizing.PER_PARAMETER, -1, -1, -1, 103, 103, 103),
/** Per-parameter key count, the run length starting at [PARAM_KEY_START] (moc 4+). */
PARAM_KEY_COUNT(ElementType.I32, Sizing.PER_PARAMETER, -1, -1, -1, 104, 104, 104),
/** Per-parameter kind (normal vs blend shape); see [ParameterType]. Absent before moc 4. */
PARAM_TYPE(ElementType.I32, Sizing.PER_PARAMETER, -1, -1, -1, 114, 114, 114),
// --- keyform-binding grid ---
PARAMETER_BINDING_COUNT(ElementType.I32, Sizing.PER_PARAMETER, 57, 57, 57, 57, 57, 57),
BINDING_KEY_OFFSET(ElementType.I32, Sizing.TABLE, 75, 75, 75, 75, 75, 75),
BINDING_KEY_COUNT(ElementType.I32, Sizing.TABLE, 76, 76, 76, 76, 76, 76),
KEYFORM_BINDING_SLOT(ElementType.I32, Sizing.TABLE, 72, 72, 72, 72, 72, 72),
KEYFORM_BINDING_START(ElementType.I32, Sizing.TABLE, 73, 73, 73, 73, 73, 73),
KEYFORM_BINDING_COUNT(ElementType.I32, Sizing.TABLE, 74, 74, 74, 74, 74, 74),
KEY_POSITIONS(ElementType.F32, Sizing.TABLE, 77, 77, 77, 77, 77, 77),
// --- parts ---
/** The part block's leading 8-byte runtime slot; all-zero on disk, sized only. */
PART_RUNTIME_SLOT(ElementType.U64, Sizing.PER_PART, 2, 2, 2, 2, 2, 2),
/** Per-part authored id, e.g. "PartHead". */
PART_ID(ElementType.ID, Sizing.PER_PART, 3, 3, 3, 3, 3, 3),
PART_KEYFORM_BINDING(ElementType.I32, Sizing.PER_PART, 4, 4, 4, 4, 4, 4),
PART_KEYFORM_BASE(ElementType.I32, Sizing.PER_PART, 5, 5, 5, 5, 5, 5),
/** Per-part keyform count (its binding's grid size). */
PART_KEYFORM_COUNT(ElementType.I32, Sizing.PER_PART, 6, 6, 6, 6, 6, 6),
/**
* The part's two visibility flags - read as "show my art meshes" and "show my deformers".
* Both are `1` on every part of every corpus sample and no CMO3 twin keeps a
* hidden part, so which is which is UNPINNED; nothing downstream needs the distinction, and a
* writer sets both from the part's single visibility.
*/
PART_VISIBLE_ARTMESHES(ElementType.I32, Sizing.PER_PART, 7, 7, 7, 7, 7, 7),
PART_VISIBLE_DEFORMERS(ElementType.I32, Sizing.PER_PART, 8, 8, 8, 8, 8, 8),
/** Per-part parent in the organizational tree, -1 at the root. */
PART_PARENT(ElementType.I32, Sizing.PER_PART, 9, 9, 9, 9, 9, 9),
PART_DRAW_ORDER(ElementType.F32, Sizing.TABLE, 58, 58, 58, 58, 58, 58),
// --- color channel tables (v4+) ---
COLOR_MULTIPLY_R(ElementType.F32, Sizing.TABLE, -1, -1, -1, 108, 108, 108),
COLOR_MULTIPLY_G(ElementType.F32, Sizing.TABLE, -1, -1, -1, 109, 109, 109),
COLOR_MULTIPLY_B(ElementType.F32, Sizing.TABLE, -1, -1, -1, 110, 110, 110),
COLOR_SCREEN_R(ElementType.F32, Sizing.TABLE, -1, -1, -1, 111, 111, 111),
COLOR_SCREEN_G(ElementType.F32, Sizing.TABLE, -1, -1, -1, 112, 112, 112),
COLOR_SCREEN_B(ElementType.F32, Sizing.TABLE, -1, -1, -1, 113, 113, 113),
// --- render-order group tree ---
RENDER_ORDER_CHILD_COUNT(ElementType.I32, Sizing.PER_RENDER_ORDER_GROUP, 82, 82, 82, 82, 82, 82),
/** Per-group total render-index count (recursive: drawables + offscreen slots + sub-group totals). */
RENDER_ORDER_GROUP_RENDER_COUNT(ElementType.I32, Sizing.PER_RENDER_ORDER_GROUP, 83, 83, 83, 83, 83, 83),
/** Per-group maximum child draw order (drawable draw order, or a sub-group's part draw order). */
RENDER_ORDER_GROUP_MAX_DRAW_ORDER(ElementType.I32, Sizing.PER_RENDER_ORDER_GROUP, 84, 84, 84, 84, 84, 84),
/** Per-group minimum child draw order. */
RENDER_ORDER_GROUP_MIN_DRAW_ORDER(ElementType.I32, Sizing.PER_RENDER_ORDER_GROUP, 85, 85, 85, 85, 85, 85),
RENDER_ORDER_CHILD_KIND(ElementType.I32, Sizing.TABLE, 86, 86, 86, 86, 86, 86),
RENDER_ORDER_CHILD_INDEX(ElementType.I32, Sizing.TABLE, 87, 87, 87, 87, 87, 87),
RENDER_ORDER_GROUP_INDEX(ElementType.I32, Sizing.TABLE, 88, 88, 88, 88, 88, 88),
/** Per-group start into the child tables (86/87/88): the prefix sum of [RENDER_ORDER_CHILD_COUNT]. */
RENDER_ORDER_CHILD_START(ElementType.I32, Sizing.PER_RENDER_ORDER_GROUP, 81, 81, 81, 81, 81, 81),
// --- glue ---
/** The glue block's leading 8-byte runtime slot; all-zero on disk, sized only. */
GLUE_RUNTIME_SLOT(ElementType.U64, Sizing.PER_GLUE, 89, 89, 89, 89, 89, 89),
/** Per-glue authored id, e.g. "Glue__ArtMesh48__ArtMesh49" (older bakes use "Glue_0_1_"). */
GLUE_ID(ElementType.ID, Sizing.PER_GLUE, 90, 90, 90, 90, 90, 90),
GLUE_KEYFORM_BINDING(ElementType.I32, Sizing.PER_GLUE, 91, 91, 91, 91, 91, 91),
GLUE_KEY_OFFSET(ElementType.I32, Sizing.PER_GLUE, 92, 92, 92, 92, 92, 92),
GLUE_KEY_COUNT(ElementType.I32, Sizing.PER_GLUE, 93, 93, 93, 93, 93, 93),
GLUE_MESH_A(ElementType.I32, Sizing.PER_GLUE, 94, 94, 94, 94, 94, 94),
GLUE_MESH_B(ElementType.I32, Sizing.PER_GLUE, 95, 95, 95, 95, 95, 95),
GLUE_VERTEX_START(ElementType.I32, Sizing.PER_GLUE, 96, 96, 96, 96, 96, 96),
GLUE_VERTEX_COUNT(ElementType.I32, Sizing.PER_GLUE, 97, 97, 97, 97, 97, 97),
GLUE_WEIGHTS(ElementType.F32, Sizing.TABLE, 98, 98, 98, 98, 98, 98),
GLUE_VERTEX_INDICES(ElementType.I16, Sizing.TABLE, 99, 99, 99, 99, 99, 99),
GLUE_INTENSITIES(ElementType.F32, Sizing.TABLE, 100, 100, 100, 100, 100, 100),
// --- blend shapes (moc 4+ positions / 5+ scalar fields) ---
BLENDSHAPE_WARP_OBJECT(ElementType.I32, Sizing.PER_BLENDSHAPE_WARP, -1, -1, -1, 125, 125, 125),
BLENDSHAPE_WARP_RECORD_START(ElementType.I32, Sizing.PER_BLENDSHAPE_WARP, -1, -1, -1, 126, 126, 126),
BLENDSHAPE_WARP_RECORD_COUNT(ElementType.I32, Sizing.PER_BLENDSHAPE_WARP, -1, -1, -1, 127, 127, 127),
BLENDSHAPE_MESH_OBJECT(ElementType.I32, Sizing.PER_BLENDSHAPE_MESH, -1, -1, -1, 128, 128, 128),
BLENDSHAPE_MESH_RECORD_START(ElementType.I32, Sizing.PER_BLENDSHAPE_MESH, -1, -1, -1, 129, 129, 129),
BLENDSHAPE_MESH_RECORD_COUNT(ElementType.I32, Sizing.PER_BLENDSHAPE_MESH, -1, -1, -1, 130, 130, 130),
// v6 index is 146 (same as v5); the Umamo C++ Runtime's kSrcLayout maps it to the degenerate/empty slot 143.
BLENDSHAPE_ROTATION_OBJECT(ElementType.I32, Sizing.PER_BLENDSHAPE_ROTATION, -1, -1, -1, -1, 146, 146),
BLENDSHAPE_ROTATION_RECORD_START(ElementType.I32, Sizing.PER_BLENDSHAPE_ROTATION, -1, -1, -1, -1, 147, 147),
BLENDSHAPE_ROTATION_RECORD_COUNT(ElementType.I32, Sizing.PER_BLENDSHAPE_ROTATION, -1, -1, -1, -1, 148, 148),
BLENDSHAPE_RECORD_BINDING(ElementType.I32, Sizing.TABLE, -1, -1, -1, 120, 120, 120),
BLENDSHAPE_RECORD_BASE(ElementType.I32, Sizing.TABLE, -1, -1, -1, 121, 121, 121),
BLENDSHAPE_RECORD_SUBSTART(ElementType.I32, Sizing.TABLE, -1, -1, -1, 123, 123, 123),
BLENDSHAPE_RECORD_CORNER_COUNT(ElementType.I32, Sizing.TABLE, -1, -1, -1, 124, 124, 124),
// MOC3 v4+ §5.6: redundant per-record copy of the record's binding key count (corpus-confirmed
// against Model A/Model B/Model C including v6 - see MorphTargetJoinProbeTest).
BLENDSHAPE_RECORD_KEY_COUNT(ElementType.I32, Sizing.TABLE, -1, -1, -1, 122, 122, 122),
// MOC3 v4+ §5.6: blend-weight limit ("blend shape limit") sub-binding tables. A record's
// SUBSTART/CORNER_COUNT range into SUB_INDEX yields refs into a DEDUPLICATED sub-binding pool;
// each pool entry maps another parameter (SUB_PARAMETER) through an end-clamped piecewise-linear
// (SUB_KEYS, SUB_WEIGHT_VALUES) curve addressed by SUB_KEY_OFFSET/COUNT. The record's weight
// multiplier is the MINIMUM over its refs. v4/v5 indices confirmed against Model B/Model C (v5) and
// the C-runtime layout; the v6 column is assumed = v5 pending a v6 constraint bake (every confirmed
// blend section is index-identical v5 -> v6, incl. section 122 above).
BLENDSHAPE_SUB_INDEX(ElementType.I32, Sizing.TABLE, -1, -1, -1, 131, 131, 131),
BLENDSHAPE_SUB_PARAMETER(ElementType.I32, Sizing.TABLE, -1, -1, -1, 132, 132, 132),
BLENDSHAPE_SUB_KEY_OFFSET(ElementType.I32, Sizing.TABLE, -1, -1, -1, 133, 133, 133),
BLENDSHAPE_SUB_KEY_COUNT(ElementType.I32, Sizing.TABLE, -1, -1, -1, 134, 134, 134),
BLENDSHAPE_SUB_KEYS(ElementType.F32, Sizing.TABLE, -1, -1, -1, 135, 135, 135),
BLENDSHAPE_SUB_WEIGHT_VALUES(ElementType.F32, Sizing.TABLE, -1, -1, -1, 136, 136, 136),
// MOC3 v5+ §5.6: part blend shapes (Model C carries one). v6 column assumed = v5 (same caveat).
BLENDSHAPE_PART_OBJECT(ElementType.I32, Sizing.PER_BLENDSHAPE_PART, -1, -1, -1, -1, 143, 143),
BLENDSHAPE_PART_RECORD_START(ElementType.I32, Sizing.PER_BLENDSHAPE_PART, -1, -1, -1, -1, 144, 144),
BLENDSHAPE_PART_RECORD_COUNT(ElementType.I32, Sizing.PER_BLENDSHAPE_PART, -1, -1, -1, -1, 145, 145),
BLENDSHAPE_BINDING_KEY_OFFSET(ElementType.I32, Sizing.TABLE, -1, -1, -1, 117, 117, 117),
BLENDSHAPE_BINDING_KEY_COUNT(ElementType.I32, Sizing.TABLE, -1, -1, -1, 118, 118, 118),
BLENDSHAPE_BINDING_NEUTRAL(ElementType.I32, Sizing.TABLE, -1, -1, -1, 119, 119, 119),
BLENDSHAPE_PARAMETER_BEGIN(ElementType.I32, Sizing.PER_PARAMETER, -1, -1, -1, 115, 115, 115),
BLENDSHAPE_PARAMETER_COUNT(ElementType.I32, Sizing.PER_PARAMETER, -1, -1, -1, 116, 116, 116),
/**
* MOC3 v5+ §5.6: glue blend shapes, the fourth object kind alongside warp/mesh/rotation/part.
* CountInfo 34 is zero on every corpus sample, so these are modeled for completeness (and so a
* bake SIZES them) but no glue blend shape is decoded into the document - nothing exercises them.
*/
BLENDSHAPE_GLUE_OBJECT(ElementType.I32, Sizing.PER_BLENDSHAPE_GLUE, -1, -1, -1, -1, 149, 149),
BLENDSHAPE_GLUE_RECORD_START(ElementType.I32, Sizing.PER_BLENDSHAPE_GLUE, -1, -1, -1, -1, 150, 150),
BLENDSHAPE_GLUE_RECORD_COUNT(ElementType.I32, Sizing.PER_BLENDSHAPE_GLUE, -1, -1, -1, -1, 151, 151),
// --- offscreen rendering (moc 6) ---
OFFSCREEN_OWNER_PART(ElementType.I32, Sizing.PER_OFFSCREEN, -1, -1, -1, -1, -1, 155),
OFFSCREEN_CONSTANT_FLAGS(ElementType.U8, Sizing.PER_OFFSCREEN, -1, -1, -1, -1, -1, 156),
OFFSCREEN_BLEND_MODE(ElementType.I32, Sizing.PER_OFFSCREEN, -1, -1, -1, -1, -1, 157),
OFFSCREEN_MASK_COUNT(ElementType.I32, Sizing.PER_OFFSCREEN, -1, -1, -1, -1, -1, 159),
OFFSCREEN_OPACITY(ElementType.F32, Sizing.TABLE, -1, -1, -1, -1, -1, 161),
/** Per-part index of the offscreen it owns, -1 when none (the inverse of [OFFSCREEN_OWNER_PART]). */
OFFSCREEN_BY_PART(ElementType.I32, Sizing.PER_PART, -1, -1, -1, -1, -1, 152),
/**
* Per-offscreen cumulative base into the offscreen mask PREFIX of [MASK_INDEX_DATA], offset from
* the block start (successive diffs equal [OFFSCREEN_MASK_COUNT]; Model A probe,
* OffscreenKeyformProbeTest).
*/
OFFSCREEN_MASK_BASE(ElementType.I32, Sizing.PER_OFFSCREEN, -1, -1, -1, -1, -1, 158),
/**
* Offscreen keyform → color-table row maps (multiply / screen). Observed identity on the corpus
* (the offscreen keyforms ARE the color tables' prefix rows, in offscreen order); the multiply
* vs screen split is assumed from the per-object color-base precedent, pending a discriminating
* sample. An offscreen's keyforms ride its owner part's keyform grid (Σ owner grid == CountInfo
* 36) - there is no offscreen keyform-binding section.
*/
OFFSCREEN_KEYFORM_MULTIPLY_ROW(ElementType.I32, Sizing.TABLE, -1, -1, -1, -1, -1, 162),
OFFSCREEN_KEYFORM_SCREEN_ROW(ElementType.I32, Sizing.TABLE, -1, -1, -1, -1, -1, 163),
/** The offscreen block's 8-byte runtime slot; all-zero on disk, sized only. */
OFFSCREEN_RUNTIME_SLOT(ElementType.U64, Sizing.PER_OFFSCREEN, -1, -1, -1, -1, -1, 154),
/**
* A second per-part offscreen-index map, byte-identical to [OFFSCREEN_BY_PART] on every corpus
* sample BUT Model A, where 152 is the exact inverse of [OFFSCREEN_OWNER_PART] while 160 names a
* larger set of parts matching no owner - so 152 is the reconstructible column and 160 an
* editor-internal artifact whose rule is unknown (OffscreenSectionAliasProbeTest guards the
* divergence). A writer emits the derivable inverse in both.
*/
OFFSCREEN_BY_PART_ALIAS(ElementType.I32, Sizing.PER_PART, -1, -1, -1, -1, -1, 160),
/**
* The v6 table's trailing slots. Zero-LENGTH in every corpus sample, so their element type and
* meaning are unknown; they are enumerated so the section map is complete and a coverage check can
* see them, and `U8`/`TABLE` is the neutral choice that asserts no stride.
*/
RESERVED_164(ElementType.U8, Sizing.TABLE, -1, -1, -1, -1, -1, 164),
RESERVED_165(ElementType.U8, Sizing.TABLE, -1, -1, -1, -1, -1, 165),
RESERVED_166(ElementType.U8, Sizing.TABLE, -1, -1, -1, -1, -1, 166),
;
/**
* Section-table index of this section for a moc [version], or -1 if absent.
*
* @param MocVersion version The moc version.
* @return Int The section index, or -1.
*/
public fun indexIn(version: MocVersion): Int = indexByVersion[version.byteValue - 1]
}
@@ -0,0 +1,71 @@
package org.umamo.format.moc3.moc
/**
* `.moc3` container constants and the CountInfo field indices.
*
* Section-table INDICES do not live here - every one of them is a [Section] enum entry carrying
* its element type, sizing rule, and per-version index, so `MocSections` can decode it and the
* lossless gate can check it. A bare index constant sitting alongside that enum would name a
* section neither of them can see, so what remains here is the container geometry and the
* CountInfo field numbers, which are not sections at all.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §section map</a>
*/
public object Sections {
/**
* Where the data region (and section index 0, CountInfo) begins on a moc <= 5 file; the
* header+table region fills [0, this). A moc 6 file reserves a larger region and starts its data
* at 0x16C0 instead, so a reader takes the first section's offset from the table rather than this.
* MOC3 §4.
*/
public const val DATA_SECTION_BEGIN: Int = 1984 // 0x7C0
/** Fixed width, in bytes, of every ID record (ASCII, NUL-terminated, zero-padded). */
public const val ID_STRIDE: Int = 64
// ---- CountInfo (section 0) u32 indices ----
public const val CI_PARTS: Int = 0
public const val CI_DEFORMERS: Int = 1
public const val CI_WARPS: Int = 2
public const val CI_ROTATIONS: Int = 3
public const val CI_DRAWABLES: Int = 4
public const val CI_PARAMETERS: Int = 5
// MOC3 §5.1 CountInfo fields 6-9: the flat per-KEYFORM array lengths, one entry per form rather
// than per object. Each object indexes its own run through its keyform base (sections 5/20/26/35).
public const val CI_PART_FORMS: Int = 6
public const val CI_WARP_FORMS: Int = 7
public const val CI_ROTATION_FORMS: Int = 8
public const val CI_ARTMESH_FORMS: Int = 9
// MOC3 §5.1 CountInfo field 12: the stored keyform-binding record count. Authoritative over
// object references - a mesh-less model carries one EMPTY binding (0 axes) that only static
// parts point at (probed on the ModelWithOffscreen family).
public const val CI_KEYFORM_BINDINGS: Int = 12
public const val CI_RENDER_ORDER_GROUPS: Int = 18
public const val CI_RENDER_ORDER_CHILDREN: Int = 19
public const val CI_GLUES: Int = 20
public const val CI_BLENDSHAPE_WARPS: Int = 27
public const val CI_BLENDSHAPE_MESHES: Int = 28
// MOC3 v4+ §5.6: total blend-shape sub-binding corner refs (Σ section 124) and the
// deduplicated sub-binding pool size (section 132's real element count).
public const val CI_BLENDSHAPE_SUB_CORNERS: Int = 29
public const val CI_BLENDSHAPE_SUB_BINDINGS: Int = 30
// MOC3 v5+ §5.6: blend-shape part objects. Note CountInfo is NOT hard-capped at 32 words on
// v5 - Model C (v5) carries CI 32/33; the reader is slice-length-driven, so these decode fine.
public const val CI_BLENDSHAPE_PARTS: Int = 32
public const val CI_BLENDSHAPE_ROTATIONS: Int = 33
// MOC3 v5+ §5.6: glue blend-shape objects (sections 149-151). Zero in every corpus sample, and
// the lowering deliberately writes zero here, so nothing downstream models a glue blend shape yet.
public const val CI_BLENDSHAPE_GLUES: Int = 34
// MOC3 v6 §5.1 CountInfo field 35: offscreen render targets (sections 152-163).
public const val CI_OFFSCREENS: Int = 35
// MOC3 v6 §5.6: total offscreen keyforms (Σ owner-part grid sizes; sizes section 161 and the
// color tables' offscreen prefix).
public const val CI_OFFSCREEN_KEYFORMS: Int = 36
}
@@ -0,0 +1,170 @@
package org.umamo.format.moc3.model
/**
* One keyform of an [Offscreen]: its opacity plus multiply/screen color. Offscreen keyforms ride
* the owner part's keyform grid (there is no offscreen keyform-binding section; Σ owner-part grid
* sizes == CountInfo 36), and their rows form the PREFIX of the shared color tables on moc 6.
*
* @property opacity The offscreen's opacity at this keyform (MOC3 §5.6 section 161).
* @property multiplyColor The multiply color row, or null when color tables are absent.
* @property screenColor The screen color row, or null when color tables are absent.
*/
public data class OffscreenKeyform(
val opacity: Float,
val multiplyColor: Rgb? = null,
val screenColor: Rgb? = null,
)
/** An offscreen render target (moc 6 / Cubism 5.3): composites its owner part's subtree. */
public data class Offscreen(
val ownerPartIndex: Int,
/** [org.umamo.format.moc3.moc.ConstantFlag]-style bitmask (`u8`). */
val constantFlags: Int,
/** Packed blend-mode value as stored in the file (the runtime unpacks it into color/alpha modes). */
val blendMode: Int,
val maskCount: Int,
/** Per-keyform opacity/color, parallel to the owner part's keyform grid (empty pre-extraction). */
val keyforms: List<OffscreenKeyform> = emptyList(),
/** Masking drawable indices from the offscreen suffix of MASK_INDEX_DATA (§5.6 section 80). */
val maskIndices: IntArray = IntArray(0),
) {
override fun equals(other: Any?): Boolean =
this === other ||
(
other is Offscreen &&
ownerPartIndex == other.ownerPartIndex &&
constantFlags == other.constantFlags &&
blendMode == other.blendMode &&
maskCount == other.maskCount &&
keyforms == other.keyforms &&
maskIndices.contentEquals(other.maskIndices)
)
override fun hashCode(): Int {
var hash = ownerPartIndex
hash = 31 * hash + constantFlags
hash = 31 * hash + blendMode
hash = 31 * hash + maskCount
hash = 31 * hash + keyforms.hashCode()
hash = 31 * hash + maskIndices.contentHashCode()
return hash
}
}
/** Which kind of object a [BlendShape] deltas (warps/meshes moc 4+; rotations/parts moc 5+). */
public enum class BlendShapeTarget { WARP, ART_MESH, ROTATION, PART }
/**
* One key's extracted delta payload of a [BlendShape] record, per target kind.
*
* Values are the raw per-key delta rows lifted from the shared keyform value tables (MOC3.md
* §5.6): relative to the object's grid form at the default pose, with the neutral key's row
* all-zero. Geometry stays in the space the base keyforms use (parent-relative); no coordinate
* conversion happens at the format layer. The reused keyform types carry the per-kind channels
* (positions/control points/affine plus opacity, draw order, and color), all as deltas - so an
* unauthored channel reads 0, not the channel's identity value.
*/
public sealed class BlendShapeKeyform {
/** An art-mesh record's per-key deltas (vertex positions, opacity, draw order, colors). */
public data class Mesh(val form: ArtMeshKeyform) : BlendShapeKeyform()
/** A warp record's per-key deltas (lattice control points, opacity, colors). */
public data class Warp(val form: WarpKeyform) : BlendShapeKeyform()
/** A rotation record's per-key deltas (origin/angle/scale, opacity, colors; reflects unused). */
public data class Rotation(val form: RotationKeyform) : BlendShapeKeyform()
/** A part record's per-key delta (draw order only - MOC3 §5.6 section 58 delta rows). */
public data class Part(val drawOrderDelta: Float) : BlendShapeKeyform()
}
/**
* A blend-weight limit ("blend shape limit") on a [BlendShape] record: an end-clamped
* piecewise-linear (key, weight) curve over ANOTHER parameter's value that caps the record's
* weight. A record's effective multiplier is the MINIMUM over its limits (1 when it has none).
*
* On disk (MOC3 v4+ §5.6, sections 123/124 + 131-136) records reference a DEDUPLICATED pool of
* sub-bindings; the decoder expands the pool per record, so identical curves shared by many
* records appear on each. A future lowering re-dedups by value when synthesizing the tables.
*
* @property parameterIndex The gating parameter (index into [org.umamo.format.moc3.MocDocument.parameters]).
* @property keyPositions The curve's parameter values, ascending.
* @property weights The weight cap at each key, parallel to [keyPositions].
*/
public data class BlendShapeLimit(
val parameterIndex: Int,
val keyPositions: FloatArray,
val weights: FloatArray,
) {
override fun equals(other: Any?): Boolean =
this === other ||
(
other is BlendShapeLimit &&
parameterIndex == other.parameterIndex &&
keyPositions.contentEquals(other.keyPositions) &&
weights.contentEquals(other.weights)
)
override fun hashCode(): Int {
var hash = parameterIndex
hash = 31 * hash + keyPositions.contentHashCode()
hash = 31 * hash + weights.contentHashCode()
return hash
}
}
/**
* A blend-shape record (moc 4+ for meshes/warps, moc 5+ for rotations): an additive deformation
* delta driven by one parameter. The deltas live in the shared keyform value tables at
* [recordBase] (per key) and are lifted into [keyforms]; each is relative to the object's grid
* form at the default pose, with the [neutralKeyIndex] row all-zero.
*
* @property target Kind of deformed object.
* @property targetIndex For [BlendShapeTarget.WARP]/[BlendShapeTarget.ROTATION], the deformer index
* in [org.umamo.format.moc3.MocDocument.deformers]; for
* [BlendShapeTarget.ART_MESH], the drawable index; for
* [BlendShapeTarget.PART], the part index.
* @property parameterIndex The driving parameter (index into [org.umamo.format.moc3.MocDocument.parameters]).
* @property keyPositions Parameter values at which deltas are keyed.
* @property neutralKeyIndex The key whose delta is zero (the rest shape).
* @property recordBase Base index into the keyform value tables for this record's per-key deltas.
* @property limits Blend-weight limits capping this record's weight (min-combined; empty = uncapped).
* @property keyforms Per-key delta payloads, parallel to [keyPositions] (one per key, kind
* matching [target]); see [BlendShapeKeyform] for the value conventions.
*/
public data class BlendShape(
val target: BlendShapeTarget,
val targetIndex: Int,
val parameterIndex: Int,
val keyPositions: FloatArray,
val neutralKeyIndex: Int,
val recordBase: Int,
val limits: List<BlendShapeLimit> = emptyList(),
val keyforms: List<BlendShapeKeyform> = emptyList(),
) {
override fun equals(other: Any?): Boolean =
this === other ||
(
other is BlendShape &&
target == other.target &&
targetIndex == other.targetIndex &&
parameterIndex == other.parameterIndex &&
keyPositions.contentEquals(other.keyPositions) &&
neutralKeyIndex == other.neutralKeyIndex &&
recordBase == other.recordBase &&
limits == other.limits &&
keyforms == other.keyforms
)
override fun hashCode(): Int {
var hash = target.hashCode()
hash = 31 * hash + targetIndex
hash = 31 * hash + parameterIndex
hash = 31 * hash + keyPositions.contentHashCode()
hash = 31 * hash + neutralKeyIndex
hash = 31 * hash + recordBase
hash = 31 * hash + limits.hashCode()
hash = 31 * hash + keyforms.hashCode()
return hash
}
}
@@ -0,0 +1,91 @@
package org.umamo.format.moc3.model
/** One keyform of an [ArtMesh]: the deformed vertex positions plus opacity/draw-order/color. */
public data class ArtMeshKeyform(
/** Vertex positions, `vertexCount` points as interleaved `x,y` (model space). */
val vertexPositions: FloatArray,
val opacity: Float,
val drawOrder: Float,
val multiplyColor: Rgb?,
val screenColor: Rgb?,
) {
override fun equals(other: Any?): Boolean =
this === other ||
(
other is ArtMeshKeyform &&
vertexPositions.contentEquals(other.vertexPositions) &&
opacity == other.opacity &&
drawOrder == other.drawOrder &&
multiplyColor == other.multiplyColor &&
screenColor == other.screenColor
)
override fun hashCode(): Int {
var hash = vertexPositions.contentHashCode()
hash = 31 * hash + opacity.hashCode()
hash = 31 * hash + drawOrder.hashCode()
hash = 31 * hash + (multiplyColor?.hashCode() ?: 0)
hash = 31 * hash + (screenColor?.hashCode() ?: 0)
return hash
}
}
/**
* An art mesh (drawable): static topology (UVs, triangles, mask list) plus per-keyform geometry.
*
* EN: [vertexUvs] (interleaved `u,v`) and [triangleIndices] are static; the vertex positions are
* keyed in [keyforms] over [keyformBindingIndex]'s grid. [parentDeformerIndex] is -1 for a mesh
* parented directly to its part.
*/
public data class ArtMesh(
val id: String,
val textureIndex: Int,
/** [org.umamo.format.moc3.moc.ConstantFlag] bitmask. */
val constantFlags: Int,
/**
* Packed 5.3 extended blend, colorMode or (alphaMode shl 8); 0 = legacy (the constant-flags
* 2-bit blend field applies instead). MOC3 v6 §5.6 s153.
*/
val extendedBlend: Int = 0,
/**
* MOC3 §5.6 s37: whether the art mesh is visible (the editor's eye toggle). The official editor
* normally DELETES a hidden mesh at bake time and only carries it - flagged false here - when
* "export invisible drawable" is on, which is why almost every corpus file has this true
* throughout. An Umamo export carries hidden meshes this same way unless its own export options
* asked to omit them.
*/
val isVisible: Boolean = true,
/** MOC3 §5.6 s38: the drawable's second flag; 1 throughout the corpus (see `ARTMESH_IS_ENABLED`). */
val isEnabled: Boolean = true,
val parentPartIndex: Int,
val parentDeformerIndex: Int,
val vertexUvs: FloatArray,
val triangleIndices: ShortArray,
val maskDrawableIndices: IntArray,
val keyformBindingIndex: Int,
val keyforms: List<ArtMeshKeyform>,
) {
/** Number of vertices (UVs / each keyform's positions hold this many `x,y` pairs). */
val vertexCount: Int get() = vertexUvs.size / 2
override fun equals(other: Any?): Boolean =
this === other ||
(
other is ArtMesh &&
id == other.id &&
textureIndex == other.textureIndex &&
constantFlags == other.constantFlags &&
extendedBlend == other.extendedBlend &&
isVisible == other.isVisible &&
isEnabled == other.isEnabled &&
parentPartIndex == other.parentPartIndex &&
parentDeformerIndex == other.parentDeformerIndex &&
vertexUvs.contentEquals(other.vertexUvs) &&
triangleIndices.contentEquals(other.triangleIndices) &&
maskDrawableIndices.contentEquals(other.maskDrawableIndices) &&
keyformBindingIndex == other.keyformBindingIndex &&
keyforms == other.keyforms
)
override fun hashCode(): Int = id.hashCode()
}
@@ -0,0 +1,99 @@
package org.umamo.format.moc3.model
/**
* A deformer (warp or rotation), carrying the fields every deformer shares - the moc3 deformer
* block's common head (sections 11-16), in file order.
*
* Deformers reference each other by index (their position in
* [org.umamo.format.moc3.MocDocument.deformers]), and [id] is the authored identifier the editor
* wrote alongside that index. The two hierarchies are independent: [parentDeformerIndex] is the
* deformation nesting, [parentPartIndex] the organizational tree.
*/
public sealed class Deformer {
/** MOC3 §5.6 s11: the authored id, e.g. "Warp349" or "B_LEG_01". */
public abstract val id: String
/** MOC3 §5.6 s12: the deformer's keyform-binding (parameter grid) index. */
public abstract val keyformBindingIndex: Int
/** MOC3 §5.6 s13: whether the deformer is visible (the editor's eye toggle). */
public abstract val isVisible: Boolean
/** MOC3 §5.6 s14: the deformer's second flag; 1 throughout the corpus (see `DEFORMER_IS_ENABLED`). */
public abstract val isEnabled: Boolean
/** MOC3 §5.6 s15: the part this deformer belongs to, -1 at the root. */
public abstract val parentPartIndex: Int
/** MOC3 §5.6 s16: the parent in the deformation hierarchy, -1 for a root deformer. */
public abstract val parentDeformerIndex: Int
}
/** One keyform of a [WarpDeformer]: the deformed control-point grid plus opacity/color. */
public data class WarpKeyform(
/** Control points, `(columns+1)·(rows+1)` points as interleaved `x,y`. */
val controlPoints: FloatArray,
val opacity: Float,
val multiplyColor: Rgb?,
val screenColor: Rgb?,
) {
override fun equals(other: Any?): Boolean =
this === other ||
(
other is WarpKeyform &&
controlPoints.contentEquals(other.controlPoints) &&
opacity == other.opacity &&
multiplyColor == other.multiplyColor &&
screenColor == other.screenColor
)
override fun hashCode(): Int {
var hash = controlPoints.contentHashCode()
hash = 31 * hash + opacity.hashCode()
hash = 31 * hash + (multiplyColor?.hashCode() ?: 0)
hash = 31 * hash + (screenColor?.hashCode() ?: 0)
return hash
}
}
/** A warp (grid) deformer: a `(columns+1)·(rows+1)` control-point lattice keyed over parameters. */
public data class WarpDeformer(
override val id: String,
override val keyformBindingIndex: Int,
override val isVisible: Boolean,
override val isEnabled: Boolean,
override val parentPartIndex: Int,
override val parentDeformerIndex: Int,
val rows: Int,
val columns: Int,
/** Interpolation mode (0 = triangle-split, non-zero = bilinear); 0 on moc < 3. */
val mode: Int,
val keyforms: List<WarpKeyform>,
) : Deformer()
/** One keyform of a [RotationDeformer]: the local affine plus opacity/color. */
public data class RotationKeyform(
val originX: Float,
val originY: Float,
/** Angle delta in degrees (added to [RotationDeformer.baseAngle]). */
val angle: Float,
val scale: Float,
val reflectX: Boolean,
val reflectY: Boolean,
val opacity: Float,
val multiplyColor: Rgb?,
val screenColor: Rgb?,
)
/** A rotation deformer: an origin/angle/scale affine keyed over parameters, plus a static base angle. */
public data class RotationDeformer(
override val id: String,
override val keyformBindingIndex: Int,
override val isVisible: Boolean,
override val isEnabled: Boolean,
override val parentPartIndex: Int,
override val parentDeformerIndex: Int,
/** Static base angle in degrees, added to each keyform's [RotationKeyform.angle]. */
val baseAngle: Float,
val keyforms: List<RotationKeyform>,
) : Deformer()
@@ -0,0 +1,62 @@
package org.umamo.format.moc3.model
/** An RGB color (each channel typically 0..1); the alpha is always 1 in moc3 color tables. */
public data class Rgb(val r: Float, val g: Float, val b: Float)
/**
* One controlling axis of a [KeyformBinding]: a parameter and the key positions sampled along it.
*
* @property parameterIndex Index into [org.umamo.format.moc3.MocDocument.parameters] of the driving parameter.
* @property keyPositions The parameter values at which keyforms exist, ascending.
*/
public data class KeyformAxis(
val parameterIndex: Int,
val keyPositions: FloatArray,
) {
/** Number of keys on this axis. */
val keyCount: Int get() = keyPositions.size
override fun equals(other: Any?): Boolean =
this === other ||
(
other is KeyformAxis &&
parameterIndex == other.parameterIndex &&
keyPositions.contentEquals(
other.keyPositions,
)
)
override fun hashCode(): Int = 31 * parameterIndex + keyPositions.contentHashCode()
}
/**
* The interpolation grid an object's keyforms are laid out on: the controlling parameter [axes]
* (in stride order, the first the fastest-varying). The number of keyforms is [gridSize]; a grid
* index decomposes to per-axis key indices via [keyIndices].
*
* EN: A static object (no controlling parameters) has no axes and a single keyform.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
public data class KeyformBinding(
val index: Int,
val axes: List<KeyformAxis>,
) {
/** Total number of keyforms = product of the axes' key counts (1 when there are no axes). */
val gridSize: Int get() = axes.fold(1) { acc, axis -> acc * axis.keyCount }
/**
* Decomposes a grid index into a per-axis key index (mixed-radix, first axis = stride 1).
*
* @param Int gridIndex A keyform index in `0 until gridSize`.
* @return IntArray The key index along each axis, in axis order.
*/
public fun keyIndices(gridIndex: Int): IntArray {
var stride = 1
return IntArray(axes.size) { axisIndex ->
val keyIndex = (gridIndex / stride) % axes[axisIndex].keyCount
stride *= axes[axisIndex].keyCount
keyIndex
}
}
}
@@ -0,0 +1,81 @@
package org.umamo.format.moc3.model
/**
* A part (visibility/draw-order group). [drawOrderKeyforms] holds the part's draw order per keyform
* of [keyformBindingIndex]'s grid (a single value when the part is static).
*/
public data class Part(
val id: String,
val parentPartIndex: Int,
val keyformBindingIndex: Int,
val drawOrderKeyforms: FloatArray,
/**
* MOC3 §5.6 s7/s8: the part's visibility. The file stores TWO flags here: Lina's research
* lists them as visible_artmeshes and visible_deformers, but without defining what they do.
* Both are 1 on every part of every corpus sample and no CMO3 twin keeps a hidden part, so
* which is which is unpinned. One field carries them: a decode takes s7, and a bake writes
* the same value to both.
*/
val isVisible: Boolean = true,
) {
override fun equals(other: Any?): Boolean =
this === other ||
(
other is Part &&
id == other.id &&
parentPartIndex == other.parentPartIndex &&
keyformBindingIndex == other.keyformBindingIndex &&
isVisible == other.isVisible &&
drawOrderKeyforms.contentEquals(other.drawOrderKeyforms)
)
override fun hashCode(): Int = id.hashCode()
}
/** A glued vertex pair: a vertex in mesh A welded to one in mesh B with per-side weights. */
public data class GlueVertexPair(
val vertexA: Int,
val vertexB: Int,
val weightA: Float,
val weightB: Float,
)
/**
* A glue: seam-welds two art meshes' shared vertices. [intensityKeyforms] modulate the weld strength
* over [keyformBindingIndex]'s grid (a single value when static).
*/
public data class Glue(
/** MOC3 §5.6 s90: the authored id, e.g. "Glue__ArtMesh48__ArtMesh49" (older bakes: "Glue_0_1_"). */
val id: String,
val meshAIndex: Int,
val meshBIndex: Int,
val keyformBindingIndex: Int,
val pairs: List<GlueVertexPair>,
val intensityKeyforms: FloatArray,
) {
override fun equals(other: Any?): Boolean =
this === other ||
(
other is Glue &&
id == other.id &&
meshAIndex == other.meshAIndex &&
meshBIndex == other.meshBIndex &&
keyformBindingIndex == other.keyformBindingIndex &&
pairs == other.pairs &&
intensityKeyforms.contentEquals(other.intensityKeyforms)
)
override fun hashCode(): Int = 31 * (31 * meshAIndex + meshBIndex) + keyformBindingIndex
}
/** A child of a [RenderOrderGroup]: a drawable (kind 0) or a nested group (kind 1). */
public data class RenderOrderChild(
val kind: Int,
/** Drawable index when [kind] is 0, else the part index used to look up the sub-group's order. */
val index: Int,
/** The nested group's record index when [kind] is 1 (else unused). */
val groupIndex: Int,
)
/** A render-order group: an ordered list of drawable/sub-group children (the draw-order tree). */
public data class RenderOrderGroup(val children: List<RenderOrderChild>)
@@ -0,0 +1,229 @@
package org.umamo.format.png
import okio.Buffer
import okio.Source
import okio.Timeout
import org.umamo.format.binary.Crc32
import org.umamo.format.binary.deflateZlib
/*
* PNG datastream plumbing: the 8-byte signature, the length/type/data/CRC chunk framing, the IDAT
* stream the decoder inflates, and the zlib compression the encoder writes it with.
*
* No host image library, so decode is byte-identical on every target; the only platform dependency is
* the zlib bridge in org.umamo.format.binary. Spec citations are to the PNG specification, second
* edition (ISO/IEC 15948:2003, W3C REC-PNG-20031110), whose section numbers differ from RFC 2083's.
*/
/** PNG spec §5.2 Datastream signature: the fixed 8-byte file magic. */
internal val PNG_SIGNATURE: ByteArray =
byteArrayOf(0x89.toByte(), 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A)
/**
* One parsed PNG chunk: its 4-character type and where its (already CRC-verified) data sits in the
* file bytes. The data stays in place rather than being copied out, because the IDAT chunks of a
* large atlas page hold hundreds of megabytes that the decoder only needs to stream through once.
*
* @param String type The chunk type.
* @param ByteArray fileBytes The complete `.png` file the chunk was read from.
* @param Int dataOffset Offset of the chunk's first data byte in [fileBytes].
* @param Int dataLength The chunk's data byte count.
*/
internal class PngChunk(val type: String, val fileBytes: ByteArray, val dataOffset: Int, val dataLength: Int) {
/**
* Copies the chunk's data out of the file bytes, for the small chunks (IHDR, PLTE, tRNS) the
* decoder reads as a whole.
*
* @return ByteArray The chunk data.
*/
fun copyData(): ByteArray = fileBytes.copyOfRange(dataOffset, dataOffset + dataLength)
}
/**
* True if [bytes] opens with the PNG signature.
*
* @param ByteArray bytes Candidate file contents.
* @return Boolean Whether the leading 8 bytes are the PNG magic.
*/
internal fun matchesPngSignature(bytes: ByteArray): Boolean {
if (bytes.size < PNG_SIGNATURE.size) {
return false
}
for (signatureIndex in PNG_SIGNATURE.indices) {
if (bytes[signatureIndex] != PNG_SIGNATURE[signatureIndex]) {
return false
}
}
return true
}
/**
* The width and height a PNG's header declares, read from the fixed offsets of its IHDR chunk without
* decoding anything else, or null when [bytes] do not open with the signature and an IHDR.
*
* PNG spec §11.2.2: IHDR is always the first chunk, 13 bytes of data, width then height as unsigned
* big-endian 32-bit integers. A dimension past what an Int holds reads as null too: no image this
* codec decodes can be that large.
*
* @param ByteArray bytes The complete `.png` file, or at least its first 24 bytes.
* @return Pair<Int, Int>? The width and height, or null.
*/
internal fun pngDimensionsOf(bytes: ByteArray): Pair<Int, Int>? {
val headerEnd = PNG_SIGNATURE.size + 16
if (bytes.size < headerEnd || !matchesPngSignature(bytes)) {
return null
}
val chunkStart = PNG_SIGNATURE.size
if (readU32BE(bytes, chunkStart) != 13L || bytes.copyOfRange(chunkStart + 4, chunkStart + 8).decodeToString() != "IHDR") {
return null
}
val width = readU32BE(bytes, chunkStart + 8)
val height = readU32BE(bytes, chunkStart + 12)
if (width > Int.MAX_VALUE || height > Int.MAX_VALUE) {
return null
}
return width.toInt() to height.toInt()
}
/**
* Reads an unsigned big-endian 32-bit integer as a Long (PNG stores lengths and CRCs this way).
*
* @param ByteArray bytes The buffer.
* @param Int at Offset of the most-significant byte.
* @return Long The value in 0..4294967295.
*/
internal fun readU32BE(bytes: ByteArray, at: Int): Long =
((bytes[at].toLong() and 0xFF) shl 24) or
((bytes[at + 1].toLong() and 0xFF) shl 16) or
((bytes[at + 2].toLong() and 0xFF) shl 8) or
(bytes[at + 3].toLong() and 0xFF)
/**
* Parses the chunk sequence after the signature, verifying each chunk's CRC-32, up to and including
* IEND. A truncated chunk or a CRC mismatch is a hard error - a valid PNG never has either.
*
* @param ByteArray bytes The complete `.png` file.
* @return List<PngChunk> The chunks in file order.
*/
internal fun readChunks(bytes: ByteArray): List<PngChunk> {
require(matchesPngSignature(bytes)) { "not a PNG (bad signature)" }
val chunks = ArrayList<PngChunk>()
var cursor = PNG_SIGNATURE.size
// PNG spec §5.3 Chunk layout: length(4) | type(4) | data(length) | crc(4).
while (cursor + 8 <= bytes.size) {
val length = readU32BE(bytes, cursor).toInt()
val typeStart = cursor + 4
val dataStart = cursor + 8
// Checked in Long: a hostile length near Int.MAX_VALUE would otherwise wrap past the bound.
require(length >= 0 && dataStart.toLong() + length + 4 <= bytes.size) { "truncated PNG chunk at offset $cursor" }
val dataEnd = dataStart + length
val type = bytes.decodeToString(typeStart, typeStart + 4)
val storedCrc = readU32BE(bytes, dataEnd)
// The CRC covers the type and data fields, which sit next to each other in the file.
val computedCrc = Crc32().also { crc -> crc.update(bytes, typeStart, 4 + length) }.value
require(storedCrc == computedCrc) {
"PNG chunk '$type' CRC mismatch (stored $storedCrc, computed $computedCrc)"
}
chunks += PngChunk(type, bytes, dataStart, length)
cursor = dataEnd + 4
if (type == "IEND") {
break
}
}
return chunks
}
/**
* CRC-32 over a chunk's type bytes followed by its data bytes, per PNG spec §5.3.
*
* @param ByteArray type The 4 type bytes.
* @param ByteArray data The chunk data.
* @return Long The CRC-32 value.
*/
internal fun crc32Of(type: ByteArray, data: ByteArray): Long {
val crc = Crc32()
crc.update(type)
crc.update(data)
return crc.value
}
/**
* Appends a complete chunk (length, type, data, CRC) to [out].
*
* PNG's multi-byte fields are all big-endian, which is Buffer.writeInt's native order — hence no
* byte-order helper here.
*
* @param Buffer out The destination buffer.
* @param String type The 4-character chunk type (ASCII).
* @param ByteArray data The chunk data (may be empty, e.g. IEND).
*/
internal fun writeChunk(out: Buffer, type: String, data: ByteArray) {
val typeBytes = type.encodeToByteArray()
out.writeInt(data.size)
out.write(typeBytes)
out.write(data)
out.writeInt(crc32Of(typeBytes, data).toInt())
}
/**
* The data of the IDAT chunks, in file order, read as the one continuous zlib stream they form (PNG
* spec §10.2 and §11.2.4: the concatenated IDAT data is one zlib datastream, split at arbitrary
* boundaries).
*
* Reads straight out of the file bytes, a piece at a time, so the compressed stream is never
* concatenated into a copy of its own.
*
* @param List<PngChunk> idatChunks The IDAT chunks in file order.
*/
internal class IdatSource(private val idatChunks: List<PngChunk>) : Source {
private var chunkIndex = 0
// Bytes of the current chunk's data already delivered.
private var consumed = 0
/**
* Appends up to [byteCount] of the next stream bytes to [sink], never crossing into the next
* chunk in one call.
*
* @param Buffer sink The buffer to append to.
* @param Long byteCount The most bytes to deliver.
* @return Long The bytes delivered, or -1 once every chunk has been read.
*/
override fun read(sink: Buffer, byteCount: Long): Long {
while (chunkIndex < idatChunks.size && consumed == idatChunks[chunkIndex].dataLength) {
chunkIndex++
consumed = 0
}
if (chunkIndex == idatChunks.size) {
return -1L
}
val chunk = idatChunks[chunkIndex]
val count = minOf(byteCount, (chunk.dataLength - consumed).toLong()).toInt()
sink.write(chunk.fileBytes, chunk.dataOffset + consumed, count)
consumed += count
return count.toLong()
}
/**
* No deadline: the bytes are already in memory.
*
* @return Timeout The no-op timeout.
*/
override fun timeout(): Timeout = Timeout.NONE
/**
* Nothing to release: the file bytes belong to the caller.
*/
override fun close() {
}
}
/**
* Compresses [data] to a zlib stream for an IDAT chunk (default deflate level).
*
* @param ByteArray data The raw, filtered scanline bytes.
* @return ByteArray The zlib-wrapped deflate stream.
*/
internal fun deflateIdat(data: ByteArray): ByteArray = deflateZlib(data)
@@ -0,0 +1,567 @@
package org.umamo.format.png
import okio.Buffer
import org.umamo.format.FileKind
import org.umamo.format.binary.ZlibStreamReader
import org.umamo.format.raster.RasterCodec
import org.umamo.format.raster.RasterImage
/**
* Pure-Kotlin PNG codec, read and write.
*
* Decodes every PNG color type (grayscale, RGB, palette, grayscale+alpha, RGBA) at bit depths
* 1/2/4/8/16, including tRNS transparency and Adam7 interlace, to the neutral straight-alpha
* RGBA8888 top-first [RasterImage]. 16-bit samples are reduced to 8 bits by the spec's most
* accurate rescaling, the linear equation of PNG spec §13.12, rather than by dropping the low byte.
* Encodes 8-bit RGBA (color type 6, non-interlaced) - the form the atlas / thumbnail pipeline
* needs. DEFLATE is the codec's only platform dependency, reached through the zlib bridge in
* org.umamo.format.binary, so it decodes byte-identically on every target (no javax.imageio /
* BitmapFactory, which is exactly what this replaces).
*
* Decoding streams: the IDAT data is inflated one scanline at a time straight out of the file
* bytes, so a decode holds the file and the output image and little else. Neither the compressed
* nor the decompressed stream is ever held whole, which is what lets a 16384-square atlas page
* decode in little more than the 1 GiB its pixels need.
*
* Spec citations are to the PNG specification, second edition (ISO/IEC 15948:2003, W3C
* REC-PNG-20031110).
*/
public object PngCodec : RasterCodec {
override val kind: FileKind = FileKind.Png
// PNG spec §11.2.2 IHDR color types.
private const val COLOR_GRAYSCALE = 0
private const val COLOR_RGB = 2
private const val COLOR_PALETTE = 3
private const val COLOR_GRAYSCALE_ALPHA = 4
private const val COLOR_RGBA = 6
private const val OPAQUE = 0xFF.toByte()
// A tRNS key no sample equals, for an image without one: raw samples are never negative.
private const val NO_KEY = -1
/** Adam7 per-pass origin and step (PNG spec §8.2): {startColumn, startRow, columnStep, rowStep}. */
private val ADAM7_PASSES =
arrayOf(
intArrayOf(0, 0, 8, 8),
intArrayOf(4, 0, 8, 8),
intArrayOf(0, 4, 4, 8),
intArrayOf(2, 0, 4, 4),
intArrayOf(0, 2, 2, 4),
intArrayOf(1, 0, 2, 2),
intArrayOf(0, 1, 1, 2),
)
/**
* True if [candidateBytes] opens with the PNG signature.
*
* @param ByteArray candidateBytes Candidate file contents.
* @return Boolean Whether the leading bytes are the PNG magic.
*/
override fun matches(candidateBytes: ByteArray): Boolean = matchesPngSignature(candidateBytes)
/**
* Decodes a `.png` into a straight-alpha RGBA8888 [RasterImage], top row first.
*
* @param ByteArray bytes The complete `.png` file.
* @return RasterImage The decoded image.
*/
override fun read(bytes: ByteArray): RasterImage {
val chunks = readChunks(bytes)
val ihdrChunk = chunks.firstOrNull { it.type == "IHDR" } ?: throw IllegalArgumentException("PNG has no IHDR")
val header = parseHeader(ihdrChunk.copyData())
val palette = chunks.firstOrNull { it.type == "PLTE" }?.copyData()
val transparency = chunks.firstOrNull { it.type == "tRNS" }?.copyData()
// PNG spec §11.2.2 Table 11.1: an indexed-color image shall carry a PLTE chunk.
require(header.colorType != COLOR_PALETTE || palette != null) { "PNG color type 3 has no PLTE chunk" }
val expander = ScanlineExpander(header, palette, transparency)
val rgba = ByteArray(header.width * header.height * 4)
// Only the scanlines IHDR describes are ever requested from the inflate, which is also its
// bound: a corrupt or hostile stream stops at the size the header promised instead of
// expanding until the process dies. A stream that ends early leaves the rows it never
// reached transparent black (best-effort, mirroring the PSD/CLIP readers).
val scanlines = ZlibStreamReader(IdatSource(chunks.filter { it.type == "IDAT" }))
try {
if (header.interlace == 1) {
for (pass in ADAM7_PASSES) {
val passWidth = passExtent(header.width, pass[0], pass[2])
val passHeight = passExtent(header.height, pass[1], pass[3])
if (passWidth == 0 || passHeight == 0) {
continue
}
decodePass(scanlines, rgba, header, expander, passWidth, passHeight, pass[0], pass[1], pass[2], pass[3])
}
} else {
decodePass(scanlines, rgba, header, expander, header.width, header.height, 0, 0, 1, 1)
}
} finally {
scanlines.close()
}
return RasterImage(header.width, header.height, rgba)
}
/**
* Encodes a [RasterImage] as an 8-bit RGBA (color type 6), non-interlaced PNG.
*
* Every scanline uses filter type 0 (None) - the simplest valid choice; DEFLATE still compresses
* it well. Round-trip is not byte-identical (zlib output varies), but decoding the result
* reproduces the input pixels exactly.
*
* @param RasterImage model The image to encode.
* @return ByteArray The complete `.png` file.
*/
override fun write(model: RasterImage): ByteArray {
val out = Buffer()
out.write(PNG_SIGNATURE)
// PNG spec §11.2.2 IHDR: width, height, bitDepth=8, colourType=6 (RGBA), compression=0, filter=0, interlace=0.
val ihdr = Buffer()
ihdr.writeInt(model.width)
ihdr.writeInt(model.height)
ihdr.writeByte(8)
ihdr.writeByte(COLOR_RGBA)
ihdr.writeByte(0)
ihdr.writeByte(0)
ihdr.writeByte(0)
writeChunk(out, "IHDR", ihdr.readByteArray())
// Raw filtered scanlines: a leading filter byte (0=None) then width*4 RGBA bytes per row.
val rowBytes = model.width * 4
val filtered = ByteArray(model.height * (1 + rowBytes))
var destination = 0
var source = 0
for (rowIndex in 0 until model.height) {
filtered[destination++] = FILTER_NONE.toByte()
model.rgba.copyInto(filtered, destination, source, source + rowBytes)
destination += rowBytes
source += rowBytes
}
writeChunk(out, "IDAT", deflateIdat(filtered))
writeChunk(out, "IEND", ByteArray(0))
return out.readByteArray()
}
/**
* The IHDR fields the decoder needs.
*
* @param Int width Image width in pixels.
* @param Int height Image height in pixels.
* @param Int bitDepth Bits per sample (per palette index for color type 3).
* @param Int colorType The PNG color type.
* @param Int interlace 0 for none, 1 for Adam7.
*/
private class PngHeader(
val width: Int,
val height: Int,
val bitDepth: Int,
val colorType: Int,
val interlace: Int,
) {
/** Samples stored per pixel. */
val channels: Int = channelCount(colorType)
/** Bits one pixel occupies in a scanline. */
val bitsPerPixel: Int = channels * bitDepth
}
/**
* Parses the 13-byte IHDR data (PNG spec §11.2.2).
*
* @param ByteArray data The IHDR chunk data.
* @return PngHeader The parsed header, validated against the spec's allowed values.
*/
private fun parseHeader(data: ByteArray): PngHeader {
require(data.size >= 13) { "PNG IHDR too short" }
// PNG spec §11.2.2 IHDR: width(4) | height(4) | bit depth(1) | color type(1) |
// compression method(1) | filter method(1) | interlace method(1).
val width = readU32BE(data, 0).toInt()
val height = readU32BE(data, 4).toInt()
val bitDepth = data[8].toInt() and 0xFF
val colorType = data[9].toInt() and 0xFF
val compressionMethod = data[10].toInt() and 0xFF
val filterMethod = data[11].toInt() and 0xFF
val interlace = data[12].toInt() and 0xFF
require(width > 0 && height > 0) { "PNG has non-positive dimensions ${width}x$height" }
// IHDR allows dimensions up to 2^31-1 each, whose product overflows the Int sizing the RGBA
// buffer; reject rather than wrap to a negative (or plausible-but-wrong) allocation.
require(width.toLong() * height * 4 <= Int.MAX_VALUE) { "PNG is too large to decode: ${width}x$height" }
require(colorType == COLOR_GRAYSCALE || colorType == COLOR_RGB || colorType == COLOR_PALETTE || colorType == COLOR_GRAYSCALE_ALPHA || colorType == COLOR_RGBA) {
"unsupported PNG color type $colorType"
}
require(bitDepthAllowed(colorType, bitDepth)) { "PNG color type $colorType does not allow bit depth $bitDepth" }
// Method 0 is the only compression method and the only filter method the spec defines.
require(compressionMethod == 0) { "unsupported PNG compression method $compressionMethod" }
require(filterMethod == 0) { "unsupported PNG filter method $filterMethod" }
require(interlace == 0 || interlace == 1) { "unsupported PNG interlace method $interlace" }
// A 16-bit RGBA scanline is twice the width of its RGBA8888 row, so it can outgrow an array
// even when the image itself fits.
require((width.toLong() * channelCount(colorType) * bitDepth + 7) / 8 < Int.MAX_VALUE) { "PNG scanline is too long to decode: ${width}x$height" }
return PngHeader(width, height, bitDepth, colorType, interlace)
}
/**
* Whether the spec allows [bitDepth] for [colorType] (PNG spec §11.2.2 Table 11.1).
*
* @param Int colorType A color type already checked to be one of the five defined ones.
* @param Int bitDepth The IHDR bit depth.
* @return Boolean True for an allowed pairing.
*/
private fun bitDepthAllowed(colorType: Int, bitDepth: Int): Boolean =
when (colorType) {
COLOR_GRAYSCALE -> bitDepth == 1 || bitDepth == 2 || bitDepth == 4 || bitDepth == 8 || bitDepth == 16
COLOR_PALETTE -> bitDepth == 1 || bitDepth == 2 || bitDepth == 4 || bitDepth == 8
else -> bitDepth == 8 || bitDepth == 16
}
/** Channels stored per pixel for a color type (palette and grayscale store one sample). */
private fun channelCount(colorType: Int): Int =
when (colorType) {
COLOR_GRAYSCALE, COLOR_PALETTE -> 1
COLOR_GRAYSCALE_ALPHA -> 2
COLOR_RGB -> 3
COLOR_RGBA -> 4
else -> throw IllegalArgumentException("unsupported PNG color type $colorType")
}
/**
* The number of pixels a reduced Adam7 pass spans along one axis (PNG spec §8.2).
*
* @param Int total The full image extent (width or height).
* @param Int start The pass origin on this axis.
* @param Int step The pass step on this axis.
* @return Int The count of samples this pass contributes on this axis (0 if the pass is empty).
*/
private fun passExtent(total: Int, start: Int, step: Int): Int =
if (total <= start) {
0
} else {
(total - start + step - 1) / step
}
/**
* Decodes one filtered sub-image (the whole image when non-interlaced, one Adam7 pass otherwise),
* pulling its scanlines from [scanlines] and scattering its pixels into [rgba] at their
* interlaced positions.
*
* @param ZlibStreamReader scanlines The inflating IDAT stream, positioned at this sub-image.
* @param ByteArray rgba The destination full-image RGBA buffer.
* @param PngHeader header The IHDR parameters.
* @param ScanlineExpander expander Turns a reconstructed scanline into RGBA.
* @param Int passWidth Pixels per row in this sub-image.
* @param Int passHeight Rows in this sub-image.
* @param Int startColumn Adam7 column origin (0 for the full image).
* @param Int startRow Adam7 row origin (0 for the full image).
* @param Int columnStep Adam7 column step (1 for the full image).
* @param Int rowStep Adam7 row step (1 for the full image).
*/
private fun decodePass(
scanlines: ZlibStreamReader,
rgba: ByteArray,
header: PngHeader,
expander: ScanlineExpander,
passWidth: Int,
passHeight: Int,
startColumn: Int,
startRow: Int,
columnStep: Int,
rowStep: Int,
) {
val bytesPerPixel = maxOf(1, (header.bitsPerPixel + 7) / 8)
val rowBytes = ((header.bitsPerPixel.toLong() * passWidth + 7) / 8).toInt()
val filterTypeByte = ByteArray(1)
// PNG spec §9.2: the first scanline of each reduced image filters against an all-zero row.
var previous = ByteArray(rowBytes)
var current = ByteArray(rowBytes)
for (rowIndex in 0 until passHeight) {
// PNG spec §9.2: each scanline opens with its filter-type byte. Past the end of a stream
// that stopped early, rows read as unfiltered zeros.
val filterType =
if (scanlines.readFully(filterTypeByte, 0, 1) == 1) {
filterTypeByte[0].toInt() and 0xFF
} else {
FILTER_NONE
}
val available = scanlines.readFully(current, 0, rowBytes)
if (available < rowBytes) {
current.fill(0, available, rowBytes)
}
unfilterScanline(filterType, current, previous, bytesPerPixel)
val imageY = startRow + rowIndex * rowStep
expander.expand(current, passWidth, rgba, (imageY * header.width + startColumn) * 4, columnStep * 4)
val swap = previous
previous = current
current = swap
}
}
/**
* Turns reconstructed scanlines into straight-alpha RGBA8888, with everything that depends only on
* IHDR, PLTE, and tRNS worked out once per image instead of once per sample.
*
* @param PngHeader header The IHDR parameters.
* @param ByteArray? palette The PLTE bytes (3 per entry), or null.
* @param ByteArray? transparency The tRNS bytes, or null.
*/
private class ScanlineExpander(private val header: PngHeader, palette: ByteArray?, transparency: ByteArray?) {
// PNG spec §11.3.2.1 tRNS for grayscale and truecolor: the single gray or RGB value, in the
// image's own sample range, that marks a pixel fully transparent.
private val keyGray = keySample(COLOR_GRAYSCALE, transparency, 0)
private val keyRed = keySample(COLOR_RGB, transparency, 0)
private val keyGreen = keySample(COLOR_RGB, transparency, 2)
private val keyBlue = keySample(COLOR_RGB, transparency, 4)
/**
* RGBA for every possible sample value of the one-sample layouts at 8 bits or fewer (palette,
* and grayscale at 1/2/4/8 bits), where a table of at most 256 entries replaces all per-pixel
* work; null for every other layout.
*/
private val sampleColors: ByteArray? = buildSampleColors(palette, transparency)
/**
* Reads one sample of a tRNS key, or [NO_KEY] when the image is not of [colorType] or its
* tRNS chunk is missing or too short to hold the key.
*
* @param Int colorType The color type the key belongs to.
* @param ByteArray? transparency The tRNS bytes, or null.
* @param Int offset Offset of the key sample's 2-byte big-endian value.
* @return Int The raw key sample, or [NO_KEY].
*/
private fun keySample(colorType: Int, transparency: ByteArray?, offset: Int): Int {
val keyBytes = if (colorType == COLOR_RGB) 6 else 2
if (header.colorType != colorType || transparency == null || transparency.size < keyBytes) {
return NO_KEY
}
return readU16(transparency, offset)
}
/**
* Builds the per-sample RGBA table for palette and low-depth grayscale images.
*
* @param ByteArray? palette The PLTE bytes, or null.
* @param ByteArray? transparency The tRNS bytes, or null.
* @return ByteArray? Four RGBA bytes per sample value, or null when the layout has no table.
*/
private fun buildSampleColors(palette: ByteArray?, transparency: ByteArray?): ByteArray? {
if (header.bitDepth > 8) {
return null
}
val entries = 1 shl header.bitDepth
return when (header.colorType) {
COLOR_PALETTE -> {
val table = ByteArray(entries * 4)
for (index in 0 until entries) {
val paletteOffset = index * 3
// An index past the palette's end stays black.
if (palette != null && paletteOffset + 2 < palette.size) {
table[index * 4] = palette[paletteOffset]
table[index * 4 + 1] = palette[paletteOffset + 1]
table[index * 4 + 2] = palette[paletteOffset + 2]
}
// PNG spec §11.3.2.1 tRNS for palette: one alpha byte per entry; unlisted entries are opaque.
table[index * 4 + 3] = if (transparency != null && index < transparency.size) transparency[index] else OPAQUE
}
table
}
COLOR_GRAYSCALE -> {
val table = ByteArray(entries * 4)
val maximumSample = entries - 1
for (sample in 0 until entries) {
// PNG spec §12.5 linear scaling up to 8 bits; 255 is a multiple of 1, 3, and 15,
// so the equation's rounding never comes into play.
val gray = (sample * 255 / maximumSample).toByte()
table[sample * 4] = gray
table[sample * 4 + 1] = gray
table[sample * 4 + 2] = gray
table[sample * 4 + 3] = if (sample == keyGray) 0 else OPAQUE
}
table
}
else -> null
}
}
/**
* Writes one reconstructed scanline's pixels into [rgba].
*
* @param ByteArray scanline The reconstructed row bytes.
* @param Int pixelCount Pixels in the row.
* @param ByteArray rgba The destination full-image RGBA buffer.
* @param Int destinationStart Byte offset in [rgba] of the row's first pixel.
* @param Int destinationStep Bytes between the row's consecutive pixels in [rgba]: 4, or a
* multiple of it for an Adam7 pass.
*/
fun expand(scanline: ByteArray, pixelCount: Int, rgba: ByteArray, destinationStart: Int, destinationStep: Int) {
val table = sampleColors
if (table != null) {
expandFromTable(table, scanline, pixelCount, rgba, destinationStart, destinationStep)
} else if (header.colorType == COLOR_RGBA && header.bitDepth == 8) {
expandRgba8(scanline, pixelCount, rgba, destinationStart, destinationStep)
} else {
expandSamples(scanline, pixelCount, rgba, destinationStart, destinationStep)
}
}
/**
* Expands a palette or low-depth grayscale scanline by table lookup.
*
* @param ByteArray table Four RGBA bytes per sample value.
* @param ByteArray scanline The reconstructed row bytes.
* @param Int pixelCount Pixels in the row.
* @param ByteArray rgba The destination full-image RGBA buffer.
* @param Int destinationStart Byte offset in [rgba] of the row's first pixel.
* @param Int destinationStep Bytes between the row's consecutive pixels in [rgba].
*/
private fun expandFromTable(table: ByteArray, scanline: ByteArray, pixelCount: Int, rgba: ByteArray, destinationStart: Int, destinationStep: Int) {
val bitDepth = header.bitDepth
val sampleMask = (1 shl bitDepth) - 1
var destination = destinationStart
for (pixelIndex in 0 until pixelCount) {
val sample =
if (bitDepth == 8) {
scanline[pixelIndex].toInt() and 0xFF
} else {
// PNG spec §7.2: samples under 8 bits pack leftmost-first from each byte's high-order bits.
val bitIndex = pixelIndex * bitDepth
(scanline[bitIndex ushr 3].toInt() ushr (8 - bitDepth - (bitIndex and 7))) and sampleMask
}
val tableOffset = sample * 4
rgba[destination] = table[tableOffset]
rgba[destination + 1] = table[tableOffset + 1]
rgba[destination + 2] = table[tableOffset + 2]
rgba[destination + 3] = table[tableOffset + 3]
destination += destinationStep
}
}
/**
* Expands an 8-bit RGBA scanline, which is already in the output layout: one copy for a full
* row, four bytes per pixel for an Adam7 pass.
*
* @param ByteArray scanline The reconstructed row bytes.
* @param Int pixelCount Pixels in the row.
* @param ByteArray rgba The destination full-image RGBA buffer.
* @param Int destinationStart Byte offset in [rgba] of the row's first pixel.
* @param Int destinationStep Bytes between the row's consecutive pixels in [rgba].
*/
private fun expandRgba8(scanline: ByteArray, pixelCount: Int, rgba: ByteArray, destinationStart: Int, destinationStep: Int) {
if (destinationStep == 4) {
scanline.copyInto(rgba, destinationStart, 0, pixelCount * 4)
return
}
var source = 0
var destination = destinationStart
for (pixelIndex in 0 until pixelCount) {
rgba[destination] = scanline[source]
rgba[destination + 1] = scanline[source + 1]
rgba[destination + 2] = scanline[source + 2]
rgba[destination + 3] = scanline[source + 3]
source += 4
destination += destinationStep
}
}
/**
* Expands the remaining layouts sample by sample: 8-bit grayscale+alpha and RGB, and every
* 16-bit layout. tRNS keys compare against the raw samples before any rescaling, as PNG spec
* §13.12 requires.
*
* @param ByteArray scanline The reconstructed row bytes.
* @param Int pixelCount Pixels in the row.
* @param ByteArray rgba The destination full-image RGBA buffer.
* @param Int destinationStart Byte offset in [rgba] of the row's first pixel.
* @param Int destinationStep Bytes between the row's consecutive pixels in [rgba].
*/
private fun expandSamples(scanline: ByteArray, pixelCount: Int, rgba: ByteArray, destinationStart: Int, destinationStep: Int) {
val channels = header.channels
val sixteenBit = header.bitDepth == 16
val sampleBytes = if (sixteenBit) 2 else 1
val pixelBytes = channels * sampleBytes
var source = 0
var destination = destinationStart
for (pixelIndex in 0 until pixelCount) {
val first = sampleAt(scanline, source, sixteenBit)
if (channels >= 3) {
val green = sampleAt(scanline, source + sampleBytes, sixteenBit)
val blue = sampleAt(scanline, source + 2 * sampleBytes, sixteenBit)
rgba[destination] = toEightBits(first, sixteenBit)
rgba[destination + 1] = toEightBits(green, sixteenBit)
rgba[destination + 2] = toEightBits(blue, sixteenBit)
rgba[destination + 3] =
if (channels == 4) {
toEightBits(sampleAt(scanline, source + 3 * sampleBytes, sixteenBit), sixteenBit)
} else if (first == keyRed && green == keyGreen && blue == keyBlue) {
0
} else {
OPAQUE
}
} else {
val gray = toEightBits(first, sixteenBit)
rgba[destination] = gray
rgba[destination + 1] = gray
rgba[destination + 2] = gray
rgba[destination + 3] =
if (channels == 2) {
toEightBits(sampleAt(scanline, source + sampleBytes, sixteenBit), sixteenBit)
} else if (first == keyGray) {
0
} else {
OPAQUE
}
}
source += pixelBytes
destination += destinationStep
}
}
}
/**
* Reads one raw 8- or 16-bit sample from a reconstructed scanline.
*
* @param ByteArray scanline The reconstructed row bytes.
* @param Int offset Offset of the sample's first byte.
* @param Boolean sixteenBit Whether samples are 16-bit (big-endian, PNG spec §7.2) rather than 8-bit.
* @return Int The raw sample value.
*/
private fun sampleAt(scanline: ByteArray, offset: Int, sixteenBit: Boolean): Int =
if (sixteenBit) {
((scanline[offset].toInt() and 0xFF) shl 8) or (scanline[offset + 1].toInt() and 0xFF)
} else {
scanline[offset].toInt() and 0xFF
}
/**
* Converts a raw 8- or 16-bit sample to the 8-bit output value.
*
* A 16-bit sample is rescaled by PNG spec §13.12's linear equation,
* floor(sample * 255 / 65535 + 0.5). The multiply-and-shift form below equals it for every 16-bit
* input, and needs no division.
*
* @param Int sample The raw sample value.
* @param Boolean sixteenBit Whether [sample] is 16-bit.
* @return Byte The 8-bit value.
*/
private fun toEightBits(sample: Int, sixteenBit: Boolean): Byte =
if (sixteenBit) {
((sample * 255 + 32895) ushr 16).toByte()
} else {
sample.toByte()
}
/**
* Reads a big-endian unsigned 16-bit value (tRNS stores each key sample this way).
*
* @param ByteArray bytes The buffer.
* @param Int at Offset of the most-significant byte.
* @return Int The value in 0..65535.
*/
private fun readU16(bytes: ByteArray, at: Int): Int =
((bytes[at].toInt() and 0xFF) shl 8) or (bytes[at + 1].toInt() and 0xFF)
}
@@ -0,0 +1,99 @@
package org.umamo.format.png
/*
* PNG scanline filtering (PNG spec §9 Filtering). Each decoded scanline is preceded by a filter-type
* byte; the filter predicts each byte from already-reconstructed neighbours and stores the residual,
* so decoding adds the prediction back. All arithmetic is modulo 256 (byte truncation).
*/
// PNG spec §9.2 Filter types.
internal const val FILTER_NONE = 0
internal const val FILTER_SUB = 1
internal const val FILTER_UP = 2
internal const val FILTER_AVERAGE = 3
internal const val FILTER_PAETH = 4
/**
* Reconstructs one scanline in place, undoing the filter of type [filterType].
*
* The bytes of the first pixel have no left neighbor (PNG spec §9.2 treats it as zero), so each
* filter handles them in a loop of their own and the main loop runs without a per-byte bounds test.
*
* @param Int filterType The filter byte (0=None, 1=Sub, 2=Up, 3=Average, 4=Paeth).
* @param ByteArray current The filtered bytes of this scanline; overwritten with the reconstruction.
* @param ByteArray previous The already-reconstructed previous scanline (all zero for the first row).
* @param Int bytesPerPixel The filter stride: bytes per complete pixel, rounded up to at least 1.
*/
internal fun unfilterScanline(filterType: Int, current: ByteArray, previous: ByteArray, bytesPerPixel: Int) {
val length = current.size
val firstPixelEnd = minOf(bytesPerPixel, length)
when (filterType) {
FILTER_NONE -> {
// Recon(x) = Filt(x).
}
FILTER_SUB -> {
// Recon(x) = Filt(x) + Recon(a); the first pixel's left neighbor is zero.
for (index in bytesPerPixel until length) {
current[index] = (current[index] + current[index - bytesPerPixel]).toByte()
}
}
FILTER_UP -> {
// Recon(x) = Filt(x) + Recon(b).
for (index in 0 until length) {
current[index] = (current[index] + previous[index]).toByte()
}
}
FILTER_AVERAGE -> {
// Recon(x) = Filt(x) + floor((Recon(a) + Recon(b)) / 2), over unsigned bytes.
for (index in 0 until firstPixelEnd) {
current[index] = (current[index] + ((previous[index].toInt() and 0xFF) ushr 1)).toByte()
}
for (index in bytesPerPixel until length) {
val left = current[index - bytesPerPixel].toInt() and 0xFF
val above = previous[index].toInt() and 0xFF
current[index] = (current[index] + ((left + above) ushr 1)).toByte()
}
}
FILTER_PAETH -> {
// Recon(x) = Filt(x) + PaethPredictor(Recon(a), Recon(b), Recon(c)). With a and c both
// zero the predictor is always b, so the first pixel reduces to Up.
for (index in 0 until firstPixelEnd) {
current[index] = (current[index] + previous[index]).toByte()
}
for (index in bytesPerPixel until length) {
val left = current[index - bytesPerPixel].toInt() and 0xFF
val above = previous[index].toInt() and 0xFF
val aboveLeft = previous[index - bytesPerPixel].toInt() and 0xFF
current[index] = (current[index] + paethPredictor(left, above, aboveLeft)).toByte()
}
}
else -> throw IllegalArgumentException("unknown PNG filter type $filterType")
}
}
/**
* The Paeth predictor (PNG spec §9.4): picks the neighbour (left, above, or above-left) closest to
* the linear estimate left + above - aboveLeft.
*
* @param Int left The reconstructed byte to the left (a in the spec).
* @param Int above The reconstructed byte above (b in the spec).
* @param Int aboveLeft The reconstructed byte above-left (c in the spec).
* @return Int The predicted byte value (0..255).
*/
internal fun paethPredictor(left: Int, above: Int, aboveLeft: Int): Int {
// The spec's pa, pb, and pc with the estimate p = a + b - c substituted in: p - a = b - c,
// p - b = a - c, and p - c = a + b - 2c.
val distanceLeft = kotlin.math.abs(above - aboveLeft)
val distanceAbove = kotlin.math.abs(left - aboveLeft)
val distanceAboveLeft = kotlin.math.abs(left + above - aboveLeft - aboveLeft)
return when {
distanceLeft <= distanceAbove && distanceLeft <= distanceAboveLeft -> left
distanceAbove <= distanceAboveLeft -> above
else -> aboveLeft
}
}
@@ -0,0 +1,407 @@
package org.umamo.format.psd
import org.umamo.format.art.LayerBlend
import org.umamo.format.art.LayerBounds
import org.umamo.format.binary.ByteReader
import kotlin.math.abs
/**
* The PSD file header plus the bits of the file structure the channel decoder needs.
*
* EN: Read from the 26-byte File Header. Canvas size and the per-layer pixel geometry both derive
* from depth and color mode, so they are surfaced here rather than guessed downstream.
* JA: PSD ファイルヘッダ(26 バイト)。キャンバスサイズと深度・カラーモードを公開する。
*
* @see <a href="https://docs.umamo.org/format/PSD.md">PSD.md §1 File Header</a>
*/
internal data class PsdHeaderInfo(
val width: Int,
val height: Int,
// PSD: number of color channels including alpha (1..56).
val channels: Int,
// PSD: bits per channel - 1, 8, 16, or 32.
val depth: Int,
// PSD: color mode - 0=Bitmap, 1=Grayscale, 2=Indexed, 3=RGB, 4=CMYK, 7=Multichannel, 8=Duotone, 9=Lab.
val colorMode: Int,
)
/**
* One entry of a layer's channel-info table: which channel it is and how many bytes its image-data
* block occupies (including the leading 2-byte compression code).
*
* PSD: channel id 0/1/2… are color channels (R/G/B for RGB, gray for grayscale, the palette index
* for indexed); -1 is the transparency (alpha) channel; -2/-3 are user/vector layer masks (no
* displayable color).
*
* @see <a href="https://docs.umamo.org/format/PSD.md">PSD.md §4 Channel image data</a>
*/
internal data class PsdChannelInfo(
val id: Int,
val length: Long,
)
/**
* One raster layer mask's geometry, from the layer's mask data block: where its pixels sit, what
* value it takes outside them, and whether it applies at all.
*
* PSD: a mask channel's plane is sized to THIS rectangle, not the layer's, and the mask reads as
* [defaultColor] everywhere outside it. The rectangle is in canvas coordinates: Photoshop sets the
* "position relative to layer" flag on every mask in the corpus and writes canvas coordinates
* anyway, so the flag is recorded but never applied.
*
* @property LayerBounds bounds The mask's rectangle in canvas pixels (top-left origin, width and height).
* @property Int defaultColor The mask value (0 or 255) outside [bounds].
* @property Boolean relativeToLayer The flags byte's bit 0, as stored; advisory only (see above).
* @property Boolean disabled Whether the mask is switched off (its channel is still stored).
*/
internal data class PsdLayerMask(
val bounds: LayerBounds,
val defaultColor: Int,
val relativeToLayer: Boolean,
val disabled: Boolean,
)
/**
* Per-layer metadata read from a PSD's "Layer and Mask Information" section.
*
* We parse this ourselves rather than leaning on a library that keeps its layer structures private:
* the record headers that carry bounds/name/opacity/clipping/blend and the channel-info table are
* trivially and reliably walked here. [channelDataOffset] is the absolute file offset of this
* layer's channel image data, computed once all records are parsed (the channel data of every layer
* is stored sequentially after the records), so [PsdRaster] can seek straight to a layer's pixels.
*
* PSD のレイヤーレコードから取り出すメタデータ。チャンネルデータの絶対オフセットも保持する。
*
* @see <a href="https://docs.umamo.org/format/PSD.md">PSD.md §3 Layer records</a>
*/
internal data class PsdLayerRecord(
val name: String,
val bounds: LayerBounds,
val opacity: Float,
val clipped: Boolean,
val blend: LayerBlend,
val visible: Boolean,
// PSD: section-divider kind from the lsct block - 0 = normal layer, 1 = open folder header,
// 2 = closed folder header, 3 = bounding divider (the hidden "</Layer group>" group end).
val dividerType: Int,
// PSD: true for a pass-through folder (blend mode key "pass"); only meaningful on folder records.
val passThrough: Boolean,
// PSD: the layer's Photoshop id from the lyid additional-layer-info block - stable across rename
// and reorder for the life of the layer; null when the writer omits lyid (some exporters do), in
// which case the reader falls back to a name+order identity.
val layerId: Int?,
// PSD: the raster layer mask stored in channel -2, or null when the layer has none. When a
// layer carries both a vector mask and a pixel mask, this describes the rasterized vector mask
// and [realUserMask] the pixel one.
val userMask: PsdLayerMask?,
// PSD: the pixel mask stored in channel -3 when the mask data block carries its "real" rectangle
// (a layer with both a vector and a pixel mask); null otherwise.
val realUserMask: PsdLayerMask?,
// PSD: this layer's channels, in storage order; their lengths drive the channel-data layout.
val channels: List<PsdChannelInfo>,
// Absolute file offset of this layer's channel image data (assigned after all records are read).
val channelDataOffset: Int,
)
/**
* The whole of a PSD relevant to art ingestion: the header, the (optional) indexed palette, and the
* per-layer records with their channel-data offsets.
*
* @see <a href="https://docs.umamo.org/format/PSD.md">PSD.md</a>
*/
internal data class PsdParse(
val header: PsdHeaderInfo,
// PSD: Color Mode Data section bytes - the 768-byte (256 x RGB) palette for indexed-color files,
// non-interleaved (all reds, then all greens, then all blues). Empty for every other color mode.
val colorModeData: ByteArray,
val records: List<PsdLayerRecord>,
)
internal object PsdLayerRecords {
/**
* Reads the header, color-mode data, and every layer record, then assigns each record the
* absolute offset of its channel image data. Records are returned in PSD storage order
* (bottom-most layer first), matching the order the channel data is stored in.
*
* @param ByteArray bytes The complete `.psd` file.
* @return PsdParse The header, palette, and per-layer records with channel-data offsets.
*/
fun parse(bytes: ByteArray): PsdParse {
// ByteReader defaults to big-endian, which is exactly PSD's byte order - no manual swaps.
val buffer = ByteReader(bytes)
// PSD: File Header - signature '8BPS', version, reserved(6), channels, height, width, depth, mode.
val signature = buffer.readAscii(4)
require(signature == "8BPS") { "not a PSD file (signature='$signature')" }
val version = buffer.readU16()
// PSD: version 1 = PSD, version 2 = PSB (large document). PSB widens the channel-length and
// section-length fields to 64-bit, which this parser does not handle, so reject it cleanly.
require(version == 1) { "PSB (PSD version 2) is not supported; only version 1" }
buffer.position = 12 // skip the 6 reserved bytes after the version
val channels = buffer.readU16()
val height = buffer.readU32AsInt()
val width = buffer.readU32AsInt()
val depth = buffer.readU16()
val colorMode = buffer.readU16()
val header = PsdHeaderInfo(width = width, height = height, channels = channels, depth = depth, colorMode = colorMode)
// PSD: Color Mode Data section (u32 length + data) - holds the indexed palette; empty otherwise.
val colorModeLength = buffer.readU32AsInt()
val colorModeData = buffer.readBytes(colorModeLength)
skipLengthPrefixed(buffer) // PSD: Image Resources section (u32 length + data) - not needed here
buffer.readU32AsInt() // PSD: Layer and Mask Information section length (unused here)
buffer.readU32AsInt() // PSD: Layer Info length (unused here)
// PSD: layer count, signed i16; a negative value means the first alpha channel holds the
// merged transparency - irrelevant to record parsing, so take the magnitude.
val layerCount = abs(buffer.readI16())
val records = ArrayList<PsdLayerRecord>(layerCount)
repeat(layerCount) {
// PSD: layer rectangle, top/left/bottom/right as i32 (top-left origin).
val top = buffer.readU32AsInt()
val left = buffer.readU32AsInt()
val bottom = buffer.readU32AsInt()
val right = buffer.readU32AsInt()
// PSD: channel count (u16), then that many channel-info records of (id i16, length u32).
val channelCount = buffer.readU16()
val channelInfos = ArrayList<PsdChannelInfo>(channelCount)
repeat(channelCount) {
val channelId = buffer.readI16() // signed: 0/1/2… color, -1 alpha, -2/-3 masks
val channelLength = buffer.readU32() // u32 byte length of the data block
channelInfos += PsdChannelInfo(id = channelId, length = channelLength)
}
val blendSignature = buffer.readAscii(4) // PSD: must be '8BIM'
require(blendSignature == "8BIM") { "bad layer blend signature '$blendSignature'" }
val blendKey = buffer.readAscii(4) // PSD: 4-char blend mode key, e.g. 'norm'
val opacityByte = buffer.readU8() // PSD: opacity 0..255
val clipping = buffer.readU8() // PSD: clipping, 0=base, 1=non-base (clipped)
// PSD: layer-record flags @ +0x0B; bit 1 (0x02) set means the layer is hidden (eye off).
val flags = buffer.readU8()
buffer.readU8() // PSD: filler (unused)
// PSD: extra data length (u32) bounds the mask + ranges + name + any additional info.
val extraLength = buffer.readU32AsInt()
val extraDataStart = buffer.position
val extraDataEnd = extraDataStart + extraLength
// PSD: folder membership is carried by lsct (Section Divider Setting) in the additional
// layer info, scanned out of the whole extra region before we consume mask/ranges/name.
val dividerType = findAdditionalInfoInt(buffer, extraDataStart, extraDataEnd, "lsct") ?: 0
// PSD: the lyid block carries Photoshop's stable per-layer id (absent when the writer omits it).
val layerId = findAdditionalInfoInt(buffer, extraDataStart, extraDataEnd, "lyid")
val (userMask, realUserMask) = readLayerMaskData(buffer)
skipLengthPrefixed(buffer) // PSD: layer blending ranges
val nameLength = buffer.readU8() // PSD: legacy Pascal-string name length
// The name is user text, not a tag: decode UTF-8, never readAscii (which is US-ASCII and
// would turn every byte of a Japanese layer name into U+FFFD). UTF-8 is what Photoshop
// writes here in practice; the strictly-correct source is the Unicode name in the luni
// additional-info block, which this parser does not read yet.
val name = buffer.readBytes(nameLength).decodeToString()
buffer.position = extraDataEnd // skip past any additional layer-info blocks we don't read
records +=
PsdLayerRecord(
name = name,
bounds = LayerBounds(left = left, top = top, width = right - left, height = bottom - top),
opacity = opacityByte / 255f,
clipped = clipping != 0,
blend = blendKeyToBlend(blendKey),
visible = (flags and 0x02) == 0,
dividerType = dividerType,
// PSD: a folder header's blend mode key is "pass" exactly when the folder is pass-through.
passThrough = blendKey == "pass",
layerId = layerId,
userMask = userMask,
realUserMask = realUserMask,
channels = channelInfos,
channelDataOffset = 0, // placeholder; filled in below once the data start is known
)
}
// PSD: the channel image data of every layer follows all the records, stored sequentially in
// the same order. The cursor now sits at the first layer's channel data, so walk the records
// accumulating channel-block lengths to give each layer its own absolute data offset.
var channelDataCursor = buffer.position.toLong()
val withOffsets =
records.map { record ->
val recordOffset = channelDataCursor.toInt()
channelDataCursor += record.channels.sumOf { channel -> channel.length }
record.copy(channelDataOffset = recordOffset)
}
return PsdParse(header = header, colorModeData = colorModeData, records = withOffsets)
}
/**
* Reads a layer record's Layer Mask / Adjustment Layer Data block, leaving the cursor just past it.
*
* PSD: u32 size (0 = no mask), then the mask rectangle (i32 top / left / bottom / right), a u8
* default color (0 or 255), and a u8 flags byte - bit 0 = rectangle relative to the layer, bit 1 =
* mask disabled, bit 4 = mask parameters follow (a flags byte, then a u8 density and / or an f64
* feather for the user and the vector mask as its bits say). A 20-byte block ends with 2 bytes of
* padding; a longer one carries the "real" user mask instead - u8 real flags, u8 real background,
* and the real rectangle - which describes the pixel mask (channel -3) when a vector mask (whose
* rasterization is channel -2) sits beside it.
*
* @param ByteReader buffer The reader, positioned at the block's size field.
* @return Pair The channel -2 mask and the channel -3 mask, either null when absent.
*/
private fun readLayerMaskData(buffer: ByteReader): Pair<PsdLayerMask?, PsdLayerMask?> {
val size = buffer.readU32AsInt()
val end = buffer.position + size
if (size < 20) {
buffer.position = end
return null to null
}
val userMask = readMaskGeometry(buffer)
if ((userMask.flagsBits and 0x10) != 0) {
val parameterFlags = buffer.readU8()
if ((parameterFlags and 0x01) != 0) {
buffer.position += 1
}
if ((parameterFlags and 0x02) != 0) {
buffer.position += 8
}
if ((parameterFlags and 0x04) != 0) {
buffer.position += 1
}
if ((parameterFlags and 0x08) != 0) {
buffer.position += 8
}
}
var realUserMask: PsdLayerMask? = null
if (end - buffer.position >= 18) {
// PSD: real flags, real user mask background, real rectangle - the pixel mask's own geometry.
val realFlags = buffer.readU8()
val realBackground = buffer.readU8()
val realTop = buffer.readU32().toInt()
val realLeft = buffer.readU32().toInt()
val realBottom = buffer.readU32().toInt()
val realRight = buffer.readU32().toInt()
realUserMask =
PsdLayerMask(
bounds = LayerBounds(left = realLeft, top = realTop, width = realRight - realLeft, height = realBottom - realTop),
defaultColor = realBackground,
relativeToLayer = (realFlags and 0x01) != 0,
disabled = (realFlags and 0x02) != 0,
)
}
buffer.position = end
return userMask.mask to realUserMask
}
/** A parsed mask rectangle with the raw flags byte, so the caller can read the parameter bit. */
private class MaskGeometry(val mask: PsdLayerMask, val flagsBits: Int)
/**
* Reads one mask geometry: the rectangle, the default color, and the flags.
*
* @param ByteReader buffer The reader, positioned at the rectangle's top field.
* @return MaskGeometry The mask plus its raw flags.
*/
private fun readMaskGeometry(buffer: ByteReader): MaskGeometry {
// PSD: the rectangle is signed - a mask can sit partly off the canvas.
val top = buffer.readU32().toInt()
val left = buffer.readU32().toInt()
val bottom = buffer.readU32().toInt()
val right = buffer.readU32().toInt()
val defaultColor = buffer.readU8()
val flags = buffer.readU8()
return MaskGeometry(
PsdLayerMask(
bounds = LayerBounds(left = left, top = top, width = right - left, height = bottom - top),
defaultColor = defaultColor,
relativeToLayer = (flags and 0x01) != 0,
disabled = (flags and 0x02) != 0,
),
flags,
)
}
/**
* Scans a layer record's extra-data region for an additional-layer-info block with the given
* 4-char [key] and returns the u32 right after the block's length field, or null when the key is
* absent. Used for both lsct (the Section Divider Setting / folder type) and lyid (the stable
* Photoshop layer id).
*
* The additional layer info is a run of blocks, each a 4-char signature ('8BIM' or '8B64'), a
* 4-char key, a u32 length, then that many data bytes - but the data padding varies by writer, so
* rather than walk block lengths we scan for the key behind a valid signature (the 8-byte
* signature+key prefix makes a false match in mask/range/name bytes effectively impossible). All
* reads here are absolute so the caller's cursor is left untouched.
*
* @param ByteReader buffer The whole-file reader.
* @param Int regionStart First byte of the extra-data region.
* @param Int regionEnd One past the last byte of the extra-data region.
* @param String key The 4-char block key to find (e.g. "lsct", "lyid").
* @return Int the u32 after the matched block's length field, or null when [key] is absent.
*/
private fun findAdditionalInfoInt(buffer: ByteReader, regionStart: Int, regionEnd: Int, key: String): Int? {
var scanPosition = regionStart
// Need 16 bytes available: signature(4) + key(4) + length(4) + value(4).
while (scanPosition + 16 <= regionEnd) {
val signature = buffer.asciiAt(scanPosition, 4)
if ((signature == "8BIM" || signature == "8B64") && buffer.asciiAt(scanPosition + 4, 4) == key) {
return buffer.u32AsInt(scanPosition + 12) // the u32 right after the block's length field
}
scanPosition++
}
return null
}
/**
* Reads a u32-length-prefixed block and advances the cursor past its payload.
*
* @param ByteReader buffer Positioned at the 4-byte length field.
*/
private fun skipLengthPrefixed(buffer: ByteReader) {
val length = buffer.readU32AsInt()
buffer.position += length
}
/**
* Maps a PSD 4-char blend-mode key to our [LayerBlend].
*
* The keys are the space-padded 4-char codes Photoshop writes (PSD.java BLEND_*). Keys with no
* neutral-model equivalent (Dissolve) and any unknown key degrade to [LayerBlend.Normal]; "pass"
* (folder pass-through) is handled separately by the caller and also reads as Normal here.
*
* @param String key The 4-character blend mode key (e.g. `"norm"`, `"mul "`).
* @return LayerBlend the matching mode, or Normal.
*/
private fun blendKeyToBlend(key: String): LayerBlend =
// PSD: blend mode keys (Adobe Photoshop File Format, "Blend mode key"); see PSD.java BLEND_*.
when (key) {
"norm" -> LayerBlend.Normal
"dark" -> LayerBlend.Darken
"mul " -> LayerBlend.Multiply
"idiv" -> LayerBlend.ColorBurn // PSD "idiv" = Color Burn
"lbrn" -> LayerBlend.LinearBurn
"dkCl" -> LayerBlend.DarkerColor
"lite" -> LayerBlend.Lighten
"scrn" -> LayerBlend.Screen
"div " -> LayerBlend.ColorDodge
"lddg" -> LayerBlend.Add // linear dodge (add)
"lgCl" -> LayerBlend.LighterColor
"over" -> LayerBlend.Overlay
"sLit" -> LayerBlend.SoftLight
"hLit" -> LayerBlend.HardLight
"vLit" -> LayerBlend.VividLight
"lLit" -> LayerBlend.LinearLight
"pLit" -> LayerBlend.PinLight
"hMix" -> LayerBlend.HardMix
"diff" -> LayerBlend.Difference
"smud" -> LayerBlend.Exclusion // PSD "smud" = Exclusion
"fsub" -> LayerBlend.Subtract
"fdiv" -> LayerBlend.Divide
"hue " -> LayerBlend.Hue
"sat " -> LayerBlend.Saturation
"colr" -> LayerBlend.Color
"lum " -> LayerBlend.Luminosity
else -> LayerBlend.Normal
}
}
@@ -0,0 +1,535 @@
// Ported from TwelveMonkeys imageio-psd (BSD-3-Clause, Copyright (c) 2013-2020 Harald Kuhr).
// The channel decompression (PackBits RLE, ZIP, ZIP-with-prediction) and the per-depth/per-mode
// sample assembly follow PSDImageReader, PSDUtil, and HorizontalDeDifferencingStream. See CREDITS.md.
package org.umamo.format.psd
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.LayerRaster
import org.umamo.format.binary.inflateZlib
/**
* Decodes one PSD layer's channel image data into a straight-alpha RGBA8888 [LayerRaster].
*
* A pure-Kotlin pixel decoder, needed because TwelveMonkeys / javax.imageio is absent on
* Android. A layer's pixels are stored as separate
* channel planes (R, G, B, alpha, …), each independently compressed; this object decompresses
* each plane, reduces it to 8 bits, and interleaves them to RGBA cropped to the layer bounds.
* A raster layer mask (channel -2, and -3 beside a vector mask) is decoded at its own rectangle
* and multiplied into the alpha, so the raster is the layer as the artist sees it - the same
* baking the CLIP reader applies. Supported: 8/16-bit RGB(A) and Grayscale, Indexed-color, and
* 1-bit Bitmap. CMYK, Lab, Multichannel, Duotone, and 32-bit float are rejected by
* [PsdReader] before reaching here.
*
* @see <a href="https://docs.umamo.org/format/PSD.md">PSD.md §4 Channel image data</a>
*/
internal object PsdRaster {
// PSD: channel image-data compression codes (PSD.java COMPRESSION_*).
private const val COMPRESSION_NONE = 0
private const val COMPRESSION_RLE = 1
private const val COMPRESSION_ZIP = 2
private const val COMPRESSION_ZIP_PREDICTION = 3
// PSD: color modes (PSD.java COLOR_MODE_*).
private const val MODE_BITMAP = 0
private const val MODE_GRAYSCALE = 1
private const val MODE_INDEXED = 2
private const val MODE_RGB = 3
// PSD: channel ids - color channels are 0/1/2…; -1 is the transparency (alpha) channel; -2 is the
// user layer mask (the rasterized vector mask when a pixel mask sits beside it), -3 that pixel mask.
private const val CHANNEL_RED = 0
private const val CHANNEL_GREEN = 1
private const val CHANNEL_BLUE = 2
private const val CHANNEL_ALPHA = -1
private const val CHANNEL_USER_MASK = -2
private const val CHANNEL_REAL_USER_MASK = -3
private const val OPAQUE = 0xFF.toByte()
/**
* Decodes [record]'s channels and assembles them into an RGBA8888 raster sized to the layer's
* bounds (top row first, straight alpha).
*
* @param ByteArray bytes The complete `.psd` file.
* @param PsdHeaderInfo header The file header (depth and color mode drive the decode).
* @param ByteArray colorModeData The Color Mode Data bytes (the indexed palette; empty otherwise).
* @param PsdLayerRecord record The layer to decode, carrying its channel-data offset.
* @return LayerRaster The cropped, straight-alpha RGBA pixels.
*/
fun decodeLayer(bytes: ByteArray, header: PsdHeaderInfo, colorModeData: ByteArray, record: PsdLayerRecord): LayerRaster {
val width = record.bounds.width
val height = record.bounds.height
if (width <= 0 || height <= 0) {
// A layer with no pixel area (an empty paint layer or a structural record): nothing to decode.
return LayerRaster(width = width.coerceAtLeast(0), height = height.coerceAtLeast(0), rgba = ByteArray(0))
}
val rowBytes = bytesPerRow(width, header.depth)
val decoded = decodePlanes(bytes, record, width, height, header.depth, rowBytes)
val planes = decoded.color
val rgba = ByteArray(width * height * 4)
when (header.colorMode) {
MODE_RGB -> assembleRgb(planes, rgba, width * height)
MODE_GRAYSCALE -> assembleGrayscale(planes, rgba, width * height)
MODE_INDEXED -> assembleIndexed(planes, colorModeData, rgba, width * height)
MODE_BITMAP -> assembleBitmap(planes, rgba, width * height)
else -> error("PSD color mode ${header.colorMode} is not supported")
}
for (maskPlane in decoded.masks) {
applyMask(rgba, width, height, record.bounds, maskPlane)
}
return LayerRaster(width = width, height = height, rgba = rgba)
}
/**
* One decoded mask: its geometry and its plane, sized to the mask's own rectangle.
*
* @property PsdLayerMask mask The mask's rectangle, default color, and flags.
* @property ByteArray plane The mask values, row-major over the mask rectangle.
*/
private class MaskPlane(val mask: PsdLayerMask, val plane: ByteArray)
/**
* A layer's decoded planes: the displayable color channels by id, and every enabled mask.
*
* @property Map color The color and alpha planes by channel id, each width*height of the layer.
* @property List masks The enabled raster masks, each over its own rectangle.
*/
private class DecodedPlanes(val color: Map<Int, ByteArray>, val masks: List<MaskPlane>)
/**
* Multiplies one mask into the raster's alpha: inside the mask rectangle the stored value, outside
* it the mask's default color, so a mask that hides everything beyond its rectangle does exactly
* that. The rectangle is always read as canvas-placed: Photoshop sets the "relative to layer"
* flag on every mask in the corpus while still writing canvas coordinates, and offsetting by the
* layer as the flag suggests throws the mask clear of its layer (every masked layer then decodes
* fully transparent).
*
* @param ByteArray rgba The layer's RGBA8888 pixels, modified in place.
* @param Int width The layer width in pixels.
* @param Int height The layer height in pixels.
* @param LayerBounds layerBounds The layer's canvas rectangle (locates the mask against it).
* @param MaskPlane maskPlane The mask to apply.
*/
private fun applyMask(rgba: ByteArray, width: Int, height: Int, layerBounds: LayerBounds, maskPlane: MaskPlane) {
val mask = maskPlane.mask
val plane = maskPlane.plane
val maskWidth = mask.bounds.width
val maskHeight = mask.bounds.height
// The mask rectangle's origin in LAYER pixel coordinates.
val originX = mask.bounds.left - layerBounds.left
val originY = mask.bounds.top - layerBounds.top
for (row in 0 until height) {
val maskRow = row - originY
val rowInside = maskRow in 0 until maskHeight
for (column in 0 until width) {
val maskColumn = column - originX
val value =
if (rowInside && maskColumn in 0 until maskWidth) {
plane[maskRow * maskWidth + maskColumn].toInt() and 0xFF
} else {
mask.defaultColor
}
if (value == 0xFF) {
continue
}
val alphaIndex = (row * width + column) * 4 + 3
val alpha = rgba[alphaIndex].toInt() and 0xFF
rgba[alphaIndex] = ((alpha * value + 127) / 255).toByte()
}
}
}
/**
* Decompresses every channel of [record] into an 8-bit-per-pixel plane: the displayable channels
* keyed by id at the layer's size, and each enabled mask channel at its own mask rectangle's size.
* A mask channel whose record describes no mask, or a disabled one, is skipped; the cursor advances
* by each channel's full block length regardless, keeping the channels sequential.
*
* @param ByteArray bytes The complete `.psd` file.
* @param PsdLayerRecord record The layer whose channels to decode.
* @param Int width Layer width in pixels.
* @param Int height Layer height in pixels.
* @param Int depth Bits per sample (1, 8, or 16).
* @param Int rowBytes Bytes per decoded channel row for this width and depth.
* @return DecodedPlanes The color planes and the enabled masks.
*/
private fun decodePlanes(bytes: ByteArray, record: PsdLayerRecord, width: Int, height: Int, depth: Int, rowBytes: Int): DecodedPlanes {
val planes = HashMap<Int, ByteArray>(record.channels.size)
val masks = ArrayList<MaskPlane>(2)
var cursor = record.channelDataOffset
for (channel in record.channels) {
val blockStart = cursor
val blockEnd = blockStart + channel.length.toInt()
cursor = blockEnd
// PSD: each channel block begins with a 2-byte compression code, then the (possibly
// compressed) sample bytes for that one channel.
if (channel.id < CHANNEL_ALPHA) {
// PSD: channel -2 is the user layer mask and -3 the real user mask; each is sized to the
// rectangle its mask geometry records, not to the layer.
val mask =
when (channel.id) {
CHANNEL_USER_MASK -> record.userMask
CHANNEL_REAL_USER_MASK -> record.realUserMask
else -> null
}
if (mask == null || mask.disabled || mask.bounds.width <= 0 || mask.bounds.height <= 0) {
continue
}
val maskRowBytes = bytesPerRow(mask.bounds.width, depth)
val compression = readU16BE(bytes, blockStart)
val samples = decodeChannel(bytes, blockStart + 2, blockEnd, compression, mask.bounds.width, mask.bounds.height, depth, maskRowBytes)
masks.add(MaskPlane(mask, samplesToPlane(samples, mask.bounds.width, mask.bounds.height, depth, maskRowBytes)))
continue
}
val compression = readU16BE(bytes, blockStart)
val samples = decodeChannel(bytes, blockStart + 2, blockEnd, compression, width, height, depth, rowBytes)
planes[channel.id] = samplesToPlane(samples, width, height, depth, rowBytes)
}
return DecodedPlanes(planes, masks)
}
/**
* Decompresses one channel's sample bytes (size height*rowBytes), per its compression code.
*
* @param ByteArray bytes The complete `.psd` file.
* @param Int dataStart Offset of the channel's sample data (just past the compression code).
* @param Int blockEnd One past the last byte of this channel's block.
* @param Int compression The PSD compression code (0=raw, 1=RLE, 2=ZIP, 3=ZIP+prediction).
* @param Int width Layer width in pixels.
* @param Int height Layer height in pixels.
* @param Int depth Bits per sample (1, 8, or 16).
* @param Int rowBytes Bytes per decoded row.
* @return ByteArray The raw, row-major sample bytes for this channel.
*/
private fun decodeChannel(bytes: ByteArray, dataStart: Int, blockEnd: Int, compression: Int, width: Int, height: Int, depth: Int, rowBytes: Int): ByteArray {
val total = height * rowBytes
return when (compression) {
COMPRESSION_NONE -> {
// PSD: raw, uncompressed sample bytes, exactly height*rowBytes.
val out = ByteArray(total)
val available = minOf(total, blockEnd - dataStart, bytes.size - dataStart)
if (available > 0) {
bytes.copyInto(out, 0, dataStart, dataStart + available)
}
out
}
COMPRESSION_RLE -> decodeRle(bytes, dataStart, height, rowBytes)
COMPRESSION_ZIP -> inflate(bytes, dataStart, blockEnd - dataStart, total)
COMPRESSION_ZIP_PREDICTION -> {
val inflated = inflate(bytes, dataStart, blockEnd - dataStart, total)
// PSD: ZIP-with-prediction stores horizontal differences; un-apply per row, per sample.
horizontalUnpredict(inflated, width, height, depth, rowBytes)
inflated
}
else -> error("unknown PSD compression $compression")
}
}
/**
* Decodes a PackBits-RLE channel: a table of per-row compressed byte counts, then the runs.
*
* PSD: for layer channels, the byte counts (one u16 per row, top-to-bottom) directly precede the
* PackBits-encoded rows of this single channel. Each row decodes to exactly rowBytes.
*
* @param ByteArray bytes The complete `.psd` file.
* @param Int dataStart Offset of the row-count table.
* @param Int height Number of rows.
* @param Int rowBytes Decoded bytes per row.
* @return ByteArray The decoded, row-major sample bytes (height*rowBytes).
*/
private fun decodeRle(bytes: ByteArray, dataStart: Int, height: Int, rowBytes: Int): ByteArray {
var countCursor = dataStart
val rowCounts = IntArray(height)
for (rowIndex in 0 until height) {
rowCounts[rowIndex] = readU16BE(bytes, countCursor)
countCursor += 2
}
val out = ByteArray(height * rowBytes)
var rowCursor = countCursor
for (rowIndex in 0 until height) {
unpackBits(bytes, rowCursor, rowCounts[rowIndex], out, rowIndex * rowBytes, rowBytes)
rowCursor += rowCounts[rowIndex]
}
return out
}
/**
* Apple PackBits run-length decode of one row.
*
* A control byte n: 0..127 copies the next n+1 bytes verbatim; -127..-1 repeats the next byte
* 1-n times; -128 is a no-op. All reads and writes are bounded so a corrupt run cannot overrun.
*
* @param ByteArray source The buffer holding the compressed bytes.
* @param Int sourceOffset Offset of this row's compressed data.
* @param Int sourceLength Compressed byte count for this row.
* @param ByteArray destination The decoded-output buffer.
* @param Int destinationOffset Offset of this row in the output.
* @param Int destinationLength Decoded bytes expected for this row (rowBytes).
*/
private fun unpackBits(source: ByteArray, sourceOffset: Int, sourceLength: Int, destination: ByteArray, destinationOffset: Int, destinationLength: Int) {
var sourceIndex = sourceOffset
val sourceEnd = minOf(sourceOffset + sourceLength, source.size)
var destinationIndex = destinationOffset
val destinationEnd = destinationOffset + destinationLength
while (sourceIndex < sourceEnd && destinationIndex < destinationEnd) {
val control = source[sourceIndex++].toInt() // signed
if (control >= 0) {
val literalCount = control + 1
var copied = 0
while (copied < literalCount && sourceIndex < sourceEnd && destinationIndex < destinationEnd) {
destination[destinationIndex++] = source[sourceIndex++]
copied++
}
} else if (control != -128) {
val runCount = 1 - control
if (sourceIndex >= sourceEnd) {
break
}
val runValue = source[sourceIndex++]
var written = 0
while (written < runCount && destinationIndex < destinationEnd) {
destination[destinationIndex++] = runValue
written++
}
}
}
}
/**
* Inflates a zlib stream of [length] bytes at [offset] into a buffer of [expected] bytes.
*
* PSD ZIP channels are standard zlib streams (header + Adler-32), so the shared platform bridge
* decodes them. A short or malformed stream yields a partially filled (zero-padded) buffer rather
* than throwing, mirroring [org.umamo.format.clip.ClipRaster].
*
* @param ByteArray bytes The buffer holding the compressed stream.
* @param Int offset Offset of the zlib stream.
* @param Int length Compressed byte count.
* @param Int expected Decompressed byte count (height*rowBytes).
* @return ByteArray The inflated bytes, sized [expected].
*/
private fun inflate(bytes: ByteArray, offset: Int, length: Int, expected: Int): ByteArray {
val inflated = inflateZlib(bytes, offset, length, expected)
if (inflated.size == expected) {
return inflated
}
// A short stream leaves the rest zero-filled; the layer is best-effort rather than a hard failure.
val out = ByteArray(expected)
inflated.copyInto(out, 0, 0, minOf(inflated.size, expected))
return out
}
/**
* Reverses the horizontal differencing predictor in place: each sample is the running sum of the
* differences along its row (per the TIFF 6.0 predictor, with one sample per pixel for planar
* channels). Only 8- and 16-bit samples occur with prediction in the supported color modes.
*
* @param ByteArray data The inflated, differenced sample bytes (modified in place).
* @param Int width Samples per row.
* @param Int height Row count.
* @param Int depth Bits per sample (8 or 16).
* @param Int rowBytes Bytes per row.
*/
private fun horizontalUnpredict(data: ByteArray, width: Int, height: Int, depth: Int, rowBytes: Int) {
when (depth) {
8 -> {
for (rowIndex in 0 until height) {
val base = rowIndex * rowBytes
for (column in 1 until width) {
val offset = base + column
if (offset < data.size) {
data[offset] = (data[offset] + data[offset - 1]).toByte()
}
}
}
}
16 -> {
for (rowIndex in 0 until height) {
val base = rowIndex * rowBytes
for (column in 1 until width) {
val offset = base + column * 2
if (offset + 1 < data.size) {
val previous = ((data[offset - 2].toInt() and 0xFF) shl 8) or (data[offset - 1].toInt() and 0xFF)
val current = ((data[offset].toInt() and 0xFF) shl 8) or (data[offset + 1].toInt() and 0xFF)
val sum = (previous + current) and 0xFFFF
data[offset] = (sum ushr 8).toByte()
data[offset + 1] = sum.toByte()
}
}
}
}
else -> error("PSD ZIP prediction unsupported for $depth-bit samples")
}
}
/**
* Reduces a channel's raw sample bytes to an 8-bit-per-pixel plane.
*
* 8-bit samples pass through; 16-bit samples keep the high (big-endian first) byte; 1-bit samples
* (Bitmap mode) expand to an intensity where a set bit is black (PSD's bitmap convention) - the
* Bitmap assembler reads this plane directly as gray.
*
* @param ByteArray samples The raw, row-major sample bytes.
* @param Int width Layer width in pixels.
* @param Int height Layer height in pixels.
* @param Int depth Bits per sample (1, 8, or 16).
* @param Int rowBytes Bytes per sample row (gives the 1-bit row stride).
* @return ByteArray A width*height plane of 8-bit values.
*/
private fun samplesToPlane(samples: ByteArray, width: Int, height: Int, depth: Int, rowBytes: Int): ByteArray {
val plane = ByteArray(width * height)
when (depth) {
8 -> {
// rowBytes == width, so the samples are already a contiguous per-pixel plane.
val count = minOf(plane.size, samples.size)
samples.copyInto(plane, 0, 0, count)
}
16 -> {
for (pixelIndex in 0 until width * height) {
val sampleOffset = pixelIndex * 2
if (sampleOffset < samples.size) {
plane[pixelIndex] = samples[sampleOffset] // big-endian high byte
}
}
}
1 -> {
for (rowIndex in 0 until height) {
val rowBase = rowIndex * rowBytes
for (column in 0 until width) {
val byteIndex = rowBase + (column ushr 3)
if (byteIndex < samples.size) {
val bit = (samples[byteIndex].toInt() ushr (7 - (column and 7))) and 1
// PSD: in Bitmap mode a set bit is black; clear is white.
plane[rowIndex * width + column] = if (bit == 1) 0 else OPAQUE
}
}
}
}
else -> error("PSD $depth-bit depth is not supported")
}
return plane
}
/**
* Interleaves R/G/B planes (and the alpha plane, or opaque if absent) into RGBA8888.
*
* @param Map planes The decoded channel planes by id.
* @param ByteArray rgba The destination RGBA buffer.
* @param Int pixelCount Number of pixels (width*height).
*/
private fun assembleRgb(planes: Map<Int, ByteArray>, rgba: ByteArray, pixelCount: Int) {
val red = planes[CHANNEL_RED]
val green = planes[CHANNEL_GREEN]
val blue = planes[CHANNEL_BLUE]
val alpha = planes[CHANNEL_ALPHA]
for (pixelIndex in 0 until pixelCount) {
val destination = pixelIndex * 4
rgba[destination] = red?.get(pixelIndex) ?: 0
rgba[destination + 1] = green?.get(pixelIndex) ?: 0
rgba[destination + 2] = blue?.get(pixelIndex) ?: 0
rgba[destination + 3] = alpha?.get(pixelIndex) ?: OPAQUE
}
}
/**
* Expands a single gray plane to R=G=B, with the alpha plane (or opaque if absent).
*
* @param Map planes The decoded channel planes by id.
* @param ByteArray rgba The destination RGBA buffer.
* @param Int pixelCount Number of pixels (width*height).
*/
private fun assembleGrayscale(planes: Map<Int, ByteArray>, rgba: ByteArray, pixelCount: Int) {
val gray = planes[CHANNEL_RED] // PSD: grayscale's single channel has id 0
val alpha = planes[CHANNEL_ALPHA]
for (pixelIndex in 0 until pixelCount) {
val destination = pixelIndex * 4
val value = gray?.get(pixelIndex) ?: 0
rgba[destination] = value
rgba[destination + 1] = value
rgba[destination + 2] = value
rgba[destination + 3] = alpha?.get(pixelIndex) ?: OPAQUE
}
}
/**
* Maps each palette index through the Color Mode Data table to RGB, with alpha (or opaque).
*
* PSD: the indexed palette is non-interleaved - all red bytes, then all green, then all blue -
* with paletteSize = colorModeData.length / 3 entries (typically 256).
*
* @param Map planes The decoded channel planes by id.
* @param ByteArray colorModeData The palette bytes.
* @param ByteArray rgba The destination RGBA buffer.
* @param Int pixelCount Number of pixels (width*height).
*/
private fun assembleIndexed(planes: Map<Int, ByteArray>, colorModeData: ByteArray, rgba: ByteArray, pixelCount: Int) {
val indices = planes[CHANNEL_RED] // PSD: the index channel has id 0
val alpha = planes[CHANNEL_ALPHA]
val paletteSize = colorModeData.size / 3
for (pixelIndex in 0 until pixelCount) {
val destination = pixelIndex * 4
val paletteIndex = (indices?.get(pixelIndex)?.toInt() ?: 0) and 0xFF
if (paletteSize > 0 && paletteIndex < paletteSize) {
rgba[destination] = colorModeData[paletteIndex]
rgba[destination + 1] = colorModeData[paletteSize + paletteIndex]
rgba[destination + 2] = colorModeData[2 * paletteSize + paletteIndex]
}
rgba[destination + 3] = alpha?.get(pixelIndex) ?: OPAQUE
}
}
/**
* Writes a 1-bit Bitmap plane as opaque gray (the plane already encodes black/white intensity).
*
* @param Map planes The decoded channel planes by id.
* @param ByteArray rgba The destination RGBA buffer.
* @param Int pixelCount Number of pixels (width*height).
*/
private fun assembleBitmap(planes: Map<Int, ByteArray>, rgba: ByteArray, pixelCount: Int) {
val value = planes[CHANNEL_RED] // PSD: bitmap's single channel has id 0
for (pixelIndex in 0 until pixelCount) {
val destination = pixelIndex * 4
val gray = value?.get(pixelIndex) ?: 0
rgba[destination] = gray
rgba[destination + 1] = gray
rgba[destination + 2] = gray
rgba[destination + 3] = OPAQUE
}
}
/**
* Bytes per decoded channel row for a given width and sample depth.
*
* @param Int width The row width in pixels.
* @param Int depth Bits per sample (1, 8, or 16).
* @return Int The packed/contiguous byte count for one row.
*/
private fun bytesPerRow(width: Int, depth: Int): Int =
when (depth) {
1 -> (width + 7) / 8 // PSD: 1-bit rows are byte-padded.
8 -> width
16 -> width * 2
else -> error("PSD $depth-bit depth is not supported")
}
/**
* Reads a big-endian unsigned 16-bit integer.
*
* @param ByteArray bytes The buffer.
* @param Int at Offset of the most-significant byte.
* @return Int The value in 0..65535.
*/
private fun readU16BE(bytes: ByteArray, at: Int): Int =
((bytes[at].toInt() and 0xFF) shl 8) or (bytes[at + 1].toInt() and 0xFF)
}
@@ -0,0 +1,181 @@
package org.umamo.format.psd
import org.umamo.format.FileKind
import org.umamo.format.art.ArtReader
import org.umamo.format.art.LayerBlend
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.LayerId
import org.umamo.format.art.LayerRaster
import org.umamo.format.art.SourceArt
import org.umamo.format.art.SourceGroup
import org.umamo.format.art.SourceLayer
/**
* Pure-Kotlin PSD reader (desktop JVM and Android).
*
* EN: [PsdLayerRecords] walks the "Layer and Mask Information" section for each layer's metadata
* (bounds/opacity/clipping/blend/name/folder structure) and channel layout; [PsdRaster] decodes
* each layer's channel pixels to straight-alpha RGBA. Both use only java.nio and java.util.zip,
* which Android ships (unlike javax.imageio, which is desktop-only) - so this lives in
* jvmAndroidMain and lights up tablets too.
* JA: 純 Kotlin の PSD 読み込み。メタデータは [PsdLayerRecords]、ピクセルは [PsdRaster]。Android でも動作。
*
* Scope: read-only; 8/16-bit RGB(A) and Grayscale, Indexed-color, and 1-bit Bitmap. CMYK, Lab,
* Multichannel, Duotone, and 32-bit float are rejected with a clear error.
*
* @see <a href="https://docs.umamo.org/format/PSD.md">PSD.md</a>
*/
object PsdReader : ArtReader {
override val kind: FileKind = FileKind.Psd
// PSD: color modes we ingest (PSD.java COLOR_MODE_*); everything else is rejected up front.
private const val MODE_BITMAP = 0
private const val MODE_GRAYSCALE = 1
private const val MODE_INDEXED = 2
private const val MODE_RGB = 3
/**
* True if [candidateBytes] starts with the PSD file signature.
*
* @param ByteArray candidateBytes Candidate file contents.
* @return Boolean Whether the leading bytes are the PSD magic.
*/
override fun matches(candidateBytes: ByteArray): Boolean = isPsd(candidateBytes)
/**
* Decodes a `.psd` into the neutral [SourceArt] model: every layer with its placement, flags,
* and decoded RGBA pixels, ordered bottom-to-top.
*
* @param ByteArray bytes The complete `.psd` file.
* @return SourceArt the canvas size and the parsed layers.
*/
override fun read(bytes: ByteArray): SourceArt {
val parse = PsdLayerRecords.parse(bytes)
val header = parse.header
// Fail fast on color modes / depths the channel decoder does not handle, with a clear message
// rather than producing garbled pixels (CMYK/Lab need ICC color management we deliberately omit).
require(header.colorMode == MODE_BITMAP || header.colorMode == MODE_GRAYSCALE || header.colorMode == MODE_INDEXED || header.colorMode == MODE_RGB) {
"PSD color mode ${header.colorMode} is not supported (only Bitmap/Grayscale/Indexed/RGB; CMYK/Lab/Multichannel/Duotone rejected)"
}
require(header.depth == 1 || header.depth == 8 || header.depth == 16) {
"PSD ${header.depth}-bit depth is not supported (only 1/8/16; 32-bit float rejected)"
}
// Walk records top-to-bottom (the reverse of bottom-to-top PSD storage) so a folder's named
// header - which sits at the top of its run - opens the group before its children, and the
// hidden bounding divider at the bottom closes it. Real layers carry the current stack path;
// folder markers are structural and are not emitted as drawable layers.
val groups = ArrayList<SourceGroup>()
val folderStack = ArrayDeque<String>()
val layersTopToBottom = ArrayList<SourceLayer>()
var emittedOrder = 0
for (recordIndex in parse.records.indices.reversed()) {
val record = parse.records[recordIndex]
when (record.dividerType) {
1, 2 -> {
// Folder header (open/closed): name the group and push it onto the path stack.
val parentPath = folderStack.joinToString("/")
val path = if (parentPath.isEmpty()) record.name else "$parentPath/${record.name}"
folderStack.addLast(record.name)
groups +=
PsdSourceGroup(
path = path,
name = record.name,
visible = record.visible,
opacity = record.opacity,
clipped = record.clipped,
blend = record.blend,
passThrough = record.passThrough,
)
}
3 -> {
// Bounding divider ("</Layer group>"): closes the innermost open folder.
if (folderStack.isNotEmpty()) {
folderStack.removeLast()
}
}
else -> {
layersTopToBottom +=
PsdSourceLayer(
// Stable identity: Photoshop's lyid (stable across rename/reorder) when present, else name+order. See docs/format/PSD.md.
id = record.layerId?.let { layerId -> LayerId("lyid:$layerId") } ?: LayerId("${record.name}#$recordIndex"),
idIsStable = record.layerId != null,
name = record.name,
visible = record.visible,
groupPath = folderStack.joinToString("/"),
order = emittedOrder++, // top-most emitted layer = 0
bounds = record.bounds,
opacity = record.opacity,
clipped = record.clipped,
blend = record.blend,
raster = PsdRaster.decodeLayer(bytes, header, parse.colorModeData, record),
)
}
}
}
// The compositor and re-import expect layers bottom-to-top (painter's order), matching KRA.
return PsdSourceArt(
widthPx = header.width,
heightPx = header.height,
layers = layersTopToBottom.asReversed(),
groups = groups,
)
}
}
/**
* True if [bytes] begins with the PSD file signature.
*
* @param ByteArray bytes Candidate file contents.
* @return Boolean Whether the leading bytes are the PSD magic.
*/
private fun isPsd(bytes: ByteArray): Boolean {
// PSD: File Header signature '8BPS' @ +0x00.
val signature = byteArrayOf(0x38, 0x42, 0x50, 0x53) // "8BPS"
if (bytes.size < signature.size) {
return false
}
for (signatureIndex in signature.indices) {
if (bytes[signatureIndex] != signature[signatureIndex]) {
return false
}
}
return true
}
/** Concrete [SourceLayer] backing a parsed PSD layer. */
private data class PsdSourceLayer(
override val id: LayerId,
override val idIsStable: Boolean,
override val name: String,
override val visible: Boolean,
override val groupPath: String,
override val order: Int,
override val bounds: LayerBounds,
override val opacity: Float,
override val clipped: Boolean,
override val blend: LayerBlend,
override val raster: LayerRaster,
) : SourceLayer
/** Concrete [SourceGroup] backing a parsed PSD folder (a section-divider header layer). */
private data class PsdSourceGroup(
override val path: String,
override val name: String,
override val visible: Boolean,
override val opacity: Float,
override val clipped: Boolean,
override val blend: LayerBlend,
override val passThrough: Boolean,
) : SourceGroup
/** Concrete [SourceArt] backing a parsed PSD document. */
private data class PsdSourceArt(
override val widthPx: Int,
override val heightPx: Int,
override val layers: List<SourceLayer>,
override val groups: List<SourceGroup>,
) : SourceArt

Some files were not shown because too many files have changed in this diff Show More