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:
@@ -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")
|
||||
}
|
||||
+67
@@ -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
|
||||
+265
@@ -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
|
||||
}
|
||||
+1253
File diff suppressed because it is too large
Load Diff
@@ -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
|
||||
}
|
||||
+66
@@ -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]
|
||||
}
|
||||
+126
@@ -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,
|
||||
)
|
||||
}
|
||||
}
|
||||
+128
@@ -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)
|
||||
}
|
||||
}
|
||||
}
|
||||
+166
@@ -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
|
||||
}
|
||||
}
|
||||
+250
@@ -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()
|
||||
}
|
||||
}
|
||||
+112
@@ -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
Reference in New Issue
Block a user