Snapshot of the Umamo working tree as it is

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

History is not carried over. The source repo is https://github.com/umamoorg/umamo.
This commit is contained in:
litruv
2026-11-03 18:20:25 +11:00
commit 8bd8fa7a0b
1347 changed files with 246161 additions and 0 deletions
+82
View File
@@ -0,0 +1,82 @@
// :android (app/android) — Android entrypoint (Activity + Compose + GLSurfaceView viewport).
// A plain Android application module (not KMP): it consumes the shared KMP libraries.
// :android — Android 起動点(Activity + Compose + GLSurfaceView ビューポート)。
plugins {
// AGP 9+ has built-in Kotlin support, so the org.jetbrains.kotlin.android plugin is gone —
// applying it now errors. AGP compiles Kotlin itself; the Compose compiler plugin hooks in.
alias(libs.plugins.androidApplication)
alias(libs.plugins.composeMultiplatform)
alias(libs.plugins.composeCompiler)
}
// Resolve the application version from ProjectInfo.kt (see gradle/project-version.gradle.kts) so
// versionName never drifts from what the About dialog shows.
apply(from = rootProject.file("gradle/project-version.gradle.kts"))
val umamoVersion = extra["umamoVersion"] as String
android {
namespace = "org.umamo.editor.android"
compileSdk = libs.versions.android.compileSdk.get().toInt()
defaultConfig {
// applicationId is the permanent Play identity; it intentionally differs from `namespace`
// so org.umamo stays a clean umbrella for a future viewer app.
applicationId = "org.umamo.editor"
minSdk = libs.versions.android.minSdk.get().toInt()
targetSdk = libs.versions.android.targetSdk.get().toInt()
// versionCode is Play's monotonic release counter — bumped by hand on release; it cannot be
// derived from a semver string.
versionCode = 1
versionName = umamoVersion
}
buildTypes {
release {
isMinifyEnabled = false
}
}
// Keep AGP's Java compilation in lockstep with Kotlin's JDK 21 target (otherwise the
// "inconsistent JVM target" error bites the moment any Java source appears).
compileOptions {
sourceCompatibility = JavaVersion.VERSION_21
targetCompatibility = JavaVersion.VERSION_21
}
packaging {
resources {
excludes += "/META-INF/LICENSE.md"
excludes += "/META-INF/LICENSE-notice.md"
}
}
}
kotlin {
jvmToolchain(21)
}
dependencies {
implementation(project(":ui"))
implementation(project(":runtime"))
// Editing core (EditorSession / Selection model): the Android host creates a per-document session
// the same way the desktop does; declared directly for parity with :runtime / :render.
implementation(project(":edit"))
implementation(project(":render"))
// androidAppStorage + the per-OS config/data dirs the settings live in; also pulls FileKit
// (api-exposed by :storage), whose Android pickers MainActivity initialises with FileKit.init.
implementation(project(":storage"))
// The Settings type returned by LocalSettings: :ui depends on :settings only via implementation, so
// MainActivity needs it on its own classpath to read settings.getString / observe settings.changes.
implementation(project(":settings"))
// setContent { } lives in androidx.activity.compose.
implementation(libs.androidx.activity.compose)
// Direct Compose Multiplatform coordinates via the version catalog — the old `compose.runtime`
// plugin aliases were deprecated in CMP 1.10/1.11. The artifacts still redirect to
// androidx.compose on this Android target (Gradle metadata), so resolution is unchanged; see the
// catalog note on the `compose-*` entries and the matching :ui commonMain block.
implementation(libs.compose.runtime)
implementation(libs.compose.foundation)
implementation(libs.compose.ui)
}
+58
View File
@@ -0,0 +1,58 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Minimal manifest: one launcher Activity. Uses a platform Material theme so no AppCompat
/ res/values theme setup is needed for the scaffold. namespace (build.gradle.kts) supplies
the package, so the manifest carries no package attribute (AGP requirement). -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="Umamo"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:theme="@android:style/Theme.Material.NoActionBar">
<!-- singleTask: a document opened from another app while the editor runs is delivered to THIS activity
(onNewIntent), where the shell asks about unsaved changes, rather than stacking a second editor. -->
<activity
android:name=".MainActivity"
android:configChanges="orientation|screenSize|keyboardHidden"
android:exported="true"
android:launchMode="singleTask">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<!-- Umamo documents (docs/format/UMA.md § 2), from a provider that knows the type. -->
<intent-filter android:label="Umamo">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="content" />
<data android:scheme="file" />
<data android:mimeType="application/vnd.umamo.uma+zip" />
</intent-filter>
<!-- Most file managers do not know the type and report a generic one, so those are matched by NAME:
pathSuffix where the platform has it (API 31), and the pathPattern ladder below it - a pattern's
".*" stops at the first dot, so each extra dot in a path needs a pattern of its own. A file that
matches by name and is not a UMA is refused by the loader's own check of the content. -->
<intent-filter android:label="Umamo">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="content" />
<data android:scheme="file" />
<data android:host="*" />
<data android:mimeType="application/octet-stream" />
<data android:mimeType="application/zip" />
<data android:pathSuffix=".uma" />
<data android:pathPattern=".*\\.uma" />
<data android:pathPattern=".*\\..*\\.uma" />
<data android:pathPattern=".*\\..*\\..*\\.uma" />
<data android:pathPattern=".*\\..*\\..*\\..*\\.uma" />
</intent-filter>
</activity>
</application>
</manifest>
@@ -0,0 +1,118 @@
package org.umamo.editor.android
import android.content.Intent
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.BackHandler
import androidx.activity.compose.setContent
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import io.github.vinceglb.filekit.FileKit
import io.github.vinceglb.filekit.dialogs.init
import org.umamo.storage.androidAppStorage
import org.umamo.ui.ProvideSettings
import org.umamo.ui.app.EditorApp
import org.umamo.ui.app.HostOpenRequests
import org.umamo.ui.app.rememberDocumentFileFor
import org.umamo.ui.app.rememberEditorSessionFor
import org.umamo.ui.app.rememberExitGuard
import org.umamo.ui.document.Document
import org.umamo.ui.document.newBlankDocument
import org.umamo.ui.theme.ProvideAppThemeFromSettings
import org.umamo.ui.theme.UmamoTheme
/**
* Android entrypoint. Mounts the same shared [EditorApp] shell desktop runs - the full File / Edit /
* Workspace / Help menu bar, document open/save through the SAF picker, the per-document editing
* session, area tree, command palette, and the Preferences window - over the Android storage/settings
* foundation. The 2D GL viewport is the one piece still platform-deferred: viewport areas render
* placeholders (viewportServiceFactory = null) until the GLES sibling of the desktop render service
* lands; the platform split stays confined to the viewport, as intended.
*/
class MainActivity : ComponentActivity() {
/**
* Documents another app hands over - a `.uma` tapped in a file manager arrives as a VIEW intent - waiting for
* the shell to open them. Held by the activity so an intent delivered to the running editor (onNewIntent)
* reaches the same shell as the one that launched it.
*/
private val openRequests = HostOpenRequests()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Only a fresh launch reads the launching intent: a recreated activity (a rotation the manifest does not
// absorb, a process restore) would otherwise reopen the file over whatever the rigger has open by then.
if (savedInstanceState == null) {
openFrom(intent)
}
// FileKit owns the activity-result registry its open/save pickers dispatch through, so it must be
// initialised once with the Activity before any file dialog (or a .clip read) runs.
FileKit.init(this)
val storage = androidAppStorage(this)
setContent {
// ProvideSettings loads settings asynchronously and gates the tree until they are ready; Android
// has no zero-window hazard (that is desktop-only), so the async load is safe here. UmamoTheme
// wraps the whole content (matching desktop's Main) so LocalUmamoColors resolves to the active
// scheme for everything created here, including the future GLES viewport host.
ProvideSettings(storage) {
ProvideAppThemeFromSettings {
UmamoTheme {
// The editor always has a document: it starts in a new, empty one.
var document by remember { mutableStateOf<Document?>(newBlankDocument()) }
val session = rememberEditorSessionFor(document)
val documentFile = rememberDocumentFileFor(document)
val exitGuard = rememberExitGuard()
// Back leaves the app (on Android 8 to 11 it destroys the root activity, edits and all), so
// while the document is dirty it asks through the same guard as File > Exit - and while a
// save is being written it goes through the guard too, which waits for the file to land.
// A clean, idle document keeps the platform's own back behavior.
val dirty = session?.dirty?.collectAsState()?.value == true
BackHandler(enabled = dirty || documentFile?.saving == true) {
exitGuard.request { finish() }
}
EditorApp(
document = document,
session = session,
documentFile = documentFile,
onOpen = { document = it },
onExit = { finish() },
exitGuard = exitGuard,
// The GLES puppet render service is the remaining platform work; until it lands the
// shared shell runs fully (menus, document, panels, thumbnails) with placeholder viewports.
viewportServiceFactory = null,
openRequests = openRequests,
)
}
}
}
}
}
/**
* A VIEW intent delivered while the editor is already running: the manifest makes the activity singleTask, so
* a second document opens here - through the shell's unsaved-changes check - instead of in a second activity.
*
* @param Intent intent The new intent.
*/
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
setIntent(intent)
openFrom(intent)
}
/**
* Forwards the document a VIEW intent names to the shell. The uri string is the same form the recent-files
* list stores, so the shell opens it the way it opens a recent file. The grant behind it is usually read-only
* and never persistable: a Save to it can fail into the save alert (Save As works), and the recent entry it
* leaves can fail later as the soft miss a stored uri already is.
*
* @param Intent? intent The intent to read.
*/
private fun openFrom(intent: Intent?) {
if (intent?.action == Intent.ACTION_VIEW) {
intent.data?.let { documentUri -> openRequests.request(documentUri.toString()) }
}
}
}
@@ -0,0 +1,9 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Adaptive launcher icon (API 26+; minSdk is 26, so this covers every target device). The OS
masks the two layers to the device shape (circle/squircle/rounded square). Background is the
solid backdrop color; foreground is the mascot rendered into the central safe zone. The legacy
mipmap-*/ic_launcher.png bitmaps remain only as a fallback for contexts that request a raw icon. -->
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
<background android:drawable="@color/ic_launcher_background" />
<foreground android:drawable="@mipmap/ic_launcher_foreground" />
</adaptive-icon>
@@ -0,0 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Round-mask variant of the adaptive icon. Same two layers as ic_launcher.xml; the OS applies the
round mask. android:roundIcon in the manifest points here for launchers that request the round form. -->
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
<background android:drawable="@color/ic_launcher_background" />
<foreground android:drawable="@mipmap/ic_launcher_foreground" />
</adaptive-icon>
Binary file not shown.

After

Width:  |  Height:  |  Size: 3.1 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.8 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.3 KiB

@@ -0,0 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Backdrop color for the adaptive launcher icon's background layer. Keep in sync with the
`background` variable in docs/design/appicon/generate.sh (which bakes the same backdrop into the
opaque desktop/window/legacy bitmaps) so a re-skin changes every surface together. -->
<resources>
<color name="ic_launcher_background">#FFFFFFFF</color>
</resources>
+45
View File
@@ -0,0 +1,45 @@
// :cli (app/cli) — the headless diagnostic tool: dump / extract / atlas / convert / diff over cmo3,
// moc3, and source artwork files.
// JVM-only on purpose: it is an operator's tool, not a shipping app target. It deliberately avoids
// :ui (whose document layer drags in Compose via LiveParams) and :edit — everything it needs is the
// :interop conversion surface plus :render's space/texture helpers.
plugins {
alias(libs.plugins.kotlinMultiplatform)
}
kotlin {
jvmToolchain(21)
jvm()
sourceSets {
jvmMain {
dependencies {
// :interop api-exposes :format and :runtime, so those come transitively.
implementation(project(":interop"))
// restMeshesToCanvasSpace / canvasToParentSpaceFor and the atlas texture helpers.
implementation(project(":render"))
}
}
}
}
// A hand-registered JavaExec rather than the application plugin: the compose.desktop application
// block is the repo's only other runnable and is not wanted here. Only file collections are
// captured (never the Project), keeping the task configuration-cache safe; `--args` works through
// JavaExec's built-in @Option.
val cliMainCompilation = kotlin.jvm().compilations.getByName("main")
val repositoryRoot = rootDir
tasks.register<JavaExec>("run") {
group = "application"
description = "Runs the Umamo diagnostic CLI; pass arguments with --args=\"dump model.moc3\"."
mainClass.set("org.umamo.cli.MainKt")
classpath(cliMainCompilation.output.allOutputs, cliMainCompilation.runtimeDependencyFiles)
// Relative file arguments should resolve against the repo root the operator invoked from, not
// this subproject's directory (JavaExec's default).
workingDir = repositoryRoot
// The atlas packer holds every source layer's pixels plus the pages it composes, and a real
// document is hundreds of megabytes of raster before a single page is allocated. The JVM
// default (a quarter of RAM) is not something to leave to the operator's machine.
maxHeapSize = "6g"
}
@@ -0,0 +1,353 @@
package org.umamo.cli
import org.umamo.format.art.SourceArt
import org.umamo.format.art.SourceLayer
import org.umamo.format.art.SourceLayerKind
import org.umamo.format.art.isEffectivelyVisible
import org.umamo.format.atlas.AtlasPackItem
import org.umamo.format.atlas.AtlasPackOptions
import org.umamo.format.atlas.AtlasPackPlacement
import org.umamo.format.atlas.AtlasPackResult
import org.umamo.format.atlas.atlasPackItems
import org.umamo.format.atlas.packAtlas
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import java.io.File
/*
* The atlas subcommand: pack a source artwork document's layers into texture atlas pages.
*
* The packer's standalone proof and inspection surface, beside the editor's own Repack Atlas command
* (document.repackAtlas): it writes the pages, reports every placement, and checks each packed tile
* back out of the page it landed on before claiming success.
*/
/** Canvas pixels past which the preview composite is skipped rather than allocated. */
private const val PREVIEW_PIXEL_CAP = 128_000_000
/**
* Runs `atlas <file> [<directory>] [options]`.
*
* Output lands in a NEW subdirectory named after the input, created under the given directory
* (default: the input file's own directory), matching how `extract` keeps its output from mixing
* into a folder that already holds other files.
*
* @param List arguments The subcommand's arguments.
* @return Int The exit code; 1 when a packed tile fails to read back out of its page.
*/
internal fun runAtlas(arguments: List<String>): Int {
val parsed =
parseArguments(
arguments,
knownFlags = setOf("--rotate", "--visible-only", "--no-shrink", "--preview"),
knownOptions = setOf("--page-size", "--gutter", "--extrude"),
)
if (parsed.positionals.isEmpty() || parsed.positionals.size > 2) {
throw CliUsageException(
"Usage: atlas <file> [<directory>] [--page-size=N] [--gutter=N] [--extrude=N] " +
"[--rotate] [--visible-only] [--no-shrink] [--preview]",
)
}
val loaded = loadInput(parsed.positionals[0])
if (loaded !is LoadedInput.SourceArtInput) {
throw CliUsageException("Atlas applies to source artwork only (psd, clip, kra, or a flat raster)")
}
val gutter = parsed.intOption("--gutter", 2)
val options =
AtlasPackOptions(
maxPageSize = parsed.intOption("--page-size", 4096),
gutter = gutter,
extrude = parsed.intOption("--extrude", minOf(2, gutter)),
allowRotation = "--rotate" in parsed.flags,
shrinkPages = "--no-shrink" !in parsed.flags,
)
val art = loaded.art
val visibleOnly = "--visible-only" in parsed.flags
val include: (SourceLayer) -> Boolean = { layer ->
layer.kind == SourceLayerKind.Raster && (!visibleOnly || art.isEffectivelyVisible(layer))
}
val includedLayers = art.layers.filter(include)
val items = art.atlasPackItems(include)
if (items.isEmpty()) {
throw CliUsageException("${loaded.file.name} has no raster layers to pack")
}
val nonRasterCount = art.layers.count { layer -> layer.kind != SourceLayerKind.Raster }
if (nonRasterCount > 0) {
System.err.println("Note: $nonRasterCount non-raster layer(s) carry no pixels and were not packed.")
}
println("Packing ${items.size} layer(s) of ${loaded.file.name} (${art.widthPx}x${art.heightPx} canvas)")
val result = packAtlas(items, options)
val outputDirectory = resolveOutputDirectory(loaded.file, parsed.positionals.getOrNull(1))
outputDirectory.mkdirs()
writePages(result, outputDirectory)
writeReport(result, includedLayers, items, options, loaded.file, outputDirectory)
reportSkips(result)
if ("--preview" in parsed.flags) {
writePreview(art, includedLayers, items, result, outputDirectory)
}
val mismatches = verifyTiles(items, result)
if (mismatches.isNotEmpty()) {
System.err.println("VERIFY FAILED: ${mismatches.size} tile(s) do not match their source pixels:")
mismatches.take(10).forEach { message -> System.err.println(" $message") }
return 1
}
println("Verified ${result.placements.size}/${result.placements.size} tiles byte-exact")
return 0
}
/**
* Resolves the output subdirectory, named after the input file.
*
* @param File inputFile The source artwork file.
* @param String? parentDirectory The caller's directory argument, when given.
* @return File The directory the pages and report write into.
*/
private fun resolveOutputDirectory(inputFile: File, parentDirectory: String?): File {
val parent = if (parentDirectory != null) File(parentDirectory) else (inputFile.parentFile ?: File("."))
val directory = File(parent, inputFile.nameWithoutExtension)
if (directory.exists()) {
System.err.println("Note: ${directory.path} already exists; its matching files will be overwritten.")
}
return directory
}
/**
* Encodes and writes every packed page.
*
* @param AtlasPackResult result The packing outcome.
* @param File outputDirectory The directory to write into.
*/
private fun writePages(result: AtlasPackResult, outputDirectory: File) {
for ((pageIndex, page) in result.pages.withIndex()) {
val target = File(outputDirectory, "page_${pageIndex.toString().padStart(2, '0')}.png")
val bytes = PngCodec.write(page)
target.writeBytes(bytes)
val occupancy = (result.pageOccupancy(pageIndex) * 100f).toInt()
println("Wrote ${target.path} (${page.width}x${page.height}, $occupancy% occupancy, ${bytes.size} bytes)")
}
}
/**
* Writes the placement report: the options the pack ran with, one line per placement, then the skips.
*
* @param AtlasPackResult result The packing outcome.
* @param List layers The layers that were offered to the packer, in the same order as [items].
* @param List items The pack items, parallel to [layers].
* @param AtlasPackOptions options The options the pack ran with.
* @param File inputFile The source artwork file.
* @param File outputDirectory The directory to write into.
*/
private fun writeReport(
result: AtlasPackResult,
layers: List<SourceLayer>,
items: List<AtlasPackItem>,
options: AtlasPackOptions,
inputFile: File,
outputDirectory: File,
) {
val layerNameByKey = items.indices.associate { itemIndex -> items[itemIndex].key to layers[itemIndex].name }
val target = File(outputDirectory, "placements.txt")
val report = StringBuilder()
report.appendLine("#atlas placements for ${inputFile.name}")
report.appendLine(
"#options pageSize=${options.maxPageSize} gutter=${options.gutter} extrude=${options.extrude} " +
"rotate=${options.allowRotation} shrink=${options.shrinkPages}",
)
for ((pageIndex, page) in result.pages.withIndex()) {
report.appendLine(
"#page $pageIndex ${page.width}x${page.height} ${(result.pageOccupancy(pageIndex) * 100f).toInt()}% occupancy",
)
}
report.appendLine("#page\tx\ty\twidth\theight\tturns\ttrimX\ttrimY\tkey\tname")
for (placement in result.placements) {
report.appendLine(
listOf(
placement.pageIndex,
placement.pageX,
placement.pageY,
placement.pageWidth,
placement.pageHeight,
placement.quarterTurns,
placement.trimLeft,
placement.trimTop,
placement.key,
layerNameByKey[placement.key].orEmpty(),
).joinToString("\t"),
)
}
for (skip in result.skipped) {
report.appendLine("#skipped\t${skip.reason}\t${skip.key}\t${layerNameByKey[skip.key].orEmpty()}")
}
target.writeText(report.toString())
println("Wrote ${target.path} (${result.placements.size} placements, ${result.skipped.size} skipped)")
}
/**
* Prints the skip tally to stderr, grouped by reason.
*
* A page that looks right while several layers quietly went missing is this stage's characteristic
* failure, so the skips are reported every run rather than only living in the written report.
*
* @param AtlasPackResult result The packing outcome.
*/
private fun reportSkips(result: AtlasPackResult) {
if (result.skipped.isEmpty()) {
return
}
for ((reason, skips) in result.skipped.groupBy { skip -> skip.reason }) {
System.err.println("Note: ${skips.size} layer(s) not packed - $reason")
}
}
/**
* Reads every packed tile back out of its page and compares it to the source pixels.
*
* This is the command's reason to exist: the atlas is a repackable indirection over the source art,
* so a page that does not reproduce the art it was built from is worthless however good it looks.
* The page-coordinate mapping ([pagePixelOf]) is written out in this file rather than shared with the
* packer, so a wrong rotation convention cannot agree with itself.
*
* @param List items The tiles that were packed.
* @param AtlasPackResult result The packing outcome.
* @return List One message per mismatching tile, empty when every tile matched.
*/
private fun verifyTiles(items: List<AtlasPackItem>, result: AtlasPackResult): List<String> {
val itemsByKey = items.associateBy { item -> item.key }
val mismatches = mutableListOf<String>()
for (placement in result.placements) {
val item = itemsByKey.getValue(placement.key)
val page = result.pages[placement.pageIndex]
var mismatch: String? = null
for (tileY in 0 until placement.trimHeight) {
for (tileX in 0 until placement.trimWidth) {
val (pageX, pageY) = pagePixelOf(placement, tileX, tileY)
val sourceOffset = ((placement.trimTop + tileY) * item.width + placement.trimLeft + tileX) * 4
val pageOffset = (pageY * page.width + pageX) * 4
for (channelIndex in 0 until 4) {
if (item.rgba[sourceOffset + channelIndex] != page.rgba[pageOffset + channelIndex]) {
mismatch = "'${placement.key}' tile pixel ($tileX, $tileY) at page ($pageX, $pageY)"
break
}
}
if (mismatch != null) {
break
}
}
if (mismatch != null) {
break
}
}
mismatch?.let { message -> mismatches.add(message) }
}
return mismatches
}
/**
* The page pixel a trimmed tile's pixel lands on under its placement, independent of the packer's
* own composition so the two can disagree; one copy serves both the byte check and the preview so
* those two cannot.
*
* @param AtlasPackPlacement placement Where the tile sits on its page.
* @param Int tileX The pixel's x within the trim.
* @param Int tileY The pixel's y within the trim.
* @return Pair<Int, Int> The page (x, y).
*/
private fun pagePixelOf(placement: AtlasPackPlacement, tileX: Int, tileY: Int): Pair<Int, Int> =
if (placement.quarterTurns == 0) {
(placement.pageX + tileX) to (placement.pageY + tileY)
} else {
(placement.pageX + tileY) to (placement.pageY + placement.trimWidth - 1 - tileX)
}
/**
* Composites the packed layers back onto a canvas-sized image, sampling from the PAGES.
*
* The byte check proves the pages carry the right pixels; this is what a human looks at to see that
* the placements also mean the right thing. Blend modes and layer opacity are ignored - it is a
* source-over stack, not a compositor - so a document leaning on them will not match its own
* application's render, which is expected rather than a packing fault.
*
* @param SourceArt art The source document, for canvas size and layer positions.
* @param List layers The layers that were offered to the packer, parallel to [items].
* @param List items The pack items, parallel to [layers].
* @param AtlasPackResult result The packing outcome.
* @param File outputDirectory The directory to write into.
*/
private fun writePreview(
art: SourceArt,
layers: List<SourceLayer>,
items: List<AtlasPackItem>,
result: AtlasPackResult,
outputDirectory: File,
) {
if (art.widthPx.toLong() * art.heightPx.toLong() > PREVIEW_PIXEL_CAP) {
System.err.println("Note: ${art.widthPx}x${art.heightPx} canvas exceeds the preview cap; preview skipped.")
return
}
val placementByKey = result.placements.associateBy { placement -> placement.key }
val canvas = ByteArray(art.widthPx * art.heightPx * 4)
// Source-over from the bottom up: order is top-most first, so the highest order draws first.
for (layerIndex in layers.indices.sortedByDescending { layerIndex -> layers[layerIndex].order }) {
val placement = placementByKey[items[layerIndex].key] ?: continue
drawPlacementOntoCanvas(canvas, art.widthPx, art.heightPx, layers[layerIndex], placement, result)
}
val target = File(outputDirectory, "preview.png")
val bytes = PngCodec.write(RasterImage(art.widthPx, art.heightPx, canvas))
target.writeBytes(bytes)
println("Wrote ${target.path} (${art.widthPx}x${art.heightPx} recomposite from the packed pages, ${bytes.size} bytes)")
}
/**
* Draws one placed layer onto the preview canvas, reading its pixels out of the atlas page.
*
* @param ByteArray canvas The canvas buffer, RGBA8888 straight alpha.
* @param Int canvasWidth The canvas width in pixels.
* @param Int canvasHeight The canvas height in pixels.
* @param SourceLayer layer The layer being drawn, for its canvas position.
* @param AtlasPackPlacement placement Where its pixels sit on a page.
* @param AtlasPackResult result The packing outcome holding the pages.
*/
private fun drawPlacementOntoCanvas(
canvas: ByteArray,
canvasWidth: Int,
canvasHeight: Int,
layer: SourceLayer,
placement: AtlasPackPlacement,
result: AtlasPackResult,
) {
val page = result.pages[placement.pageIndex]
for (tileY in 0 until placement.trimHeight) {
val canvasY = layer.bounds.top + placement.trimTop + tileY
if (canvasY < 0 || canvasY >= canvasHeight) {
continue
}
for (tileX in 0 until placement.trimWidth) {
val canvasX = layer.bounds.left + placement.trimLeft + tileX
if (canvasX < 0 || canvasX >= canvasWidth) {
continue
}
val (pageX, pageY) = pagePixelOf(placement, tileX, tileY)
val pageOffset = (pageY * page.width + pageX) * 4
val canvasOffset = (canvasY * canvasWidth + canvasX) * 4
val sourceAlpha = (page.rgba[pageOffset + 3].toInt() and 0xFF) / 255f
if (sourceAlpha <= 0f) {
continue
}
val destinationAlpha = (canvas[canvasOffset + 3].toInt() and 0xFF) / 255f
val outAlpha = sourceAlpha + destinationAlpha * (1f - sourceAlpha)
for (channelIndex in 0 until 3) {
val sourceChannel = (page.rgba[pageOffset + channelIndex].toInt() and 0xFF) / 255f
val destinationChannel = (canvas[canvasOffset + channelIndex].toInt() and 0xFF) / 255f
val blended =
(sourceChannel * sourceAlpha + destinationChannel * destinationAlpha * (1f - sourceAlpha)) / outAlpha
canvas[canvasOffset + channelIndex] = (blended * 255f + 0.5f).toInt().coerceIn(0, 255).toByte()
}
canvas[canvasOffset + 3] = (outAlpha * 255f + 0.5f).toInt().coerceIn(0, 255).toByte()
}
}
}
@@ -0,0 +1,244 @@
package org.umamo.cli
import org.umamo.format.FormatRegistry
import org.umamo.format.art.ArtReader
import org.umamo.format.art.SourceArt
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.Cmo3Model
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.json.Cdi3Json
import org.umamo.format.moc3.json.Model3Json
import org.umamo.format.raster.RasterCodec
import org.umamo.format.raster.rasterToSourceArt
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.interop.moc3.Moc3Sidecars
import org.umamo.interop.moc3.import.Moc3Import
import org.umamo.render.restMeshesToCanvasSpace
import org.umamo.runtime.model.PuppetModel
import java.io.File
import java.util.Locale
/*
* Input routing shared by every subcommand: read a file, detect its format through the same
* FormatRegistry the app uses, and (for moc3) discover the sibling family files through the
* model3.json manifest.
*/
/** A loaded input file, branched by detected format. */
internal sealed interface LoadedInput {
/** A CMO3 editor document. */
class Cmo3Input(val model: Cmo3Model, val bytes: ByteArray) : LoadedInput
/** A MOC3 runtime document plus whatever family files sat beside it. */
class Moc3Input(val document: MocDocument, val family: Moc3Family) : LoadedInput
/**
* Layered or flat source artwork: PSD, CLIP, KRA, or any of the flat raster formats read as a
* single-layer document. It carries no rig - there is no source-art to PuppetModel bridge yet
* (pipeline Phase E) - so only artwork-side commands accept it.
*/
class SourceArtInput(val art: SourceArt, val file: File) : LoadedInput
}
/**
* The MOC3 family files discovered around a moc: the manifest (when present), the display-info
* sidecar, the texture files the manifest references, and the pass-through sidecar texts.
*
* @property File mocFile The .moc3 file itself.
* @property Model3Json? manifest The parsed model3.json, or null when none was found.
* @property Cdi3Json? displayInfo The parsed cdi3.json, or null when absent.
* @property List textureFiles The manifest's texture files, resolved against its directory.
* @property List sidecars Physics/pose/userdata texts, carried through verbatim.
*/
internal class Moc3Family(
val mocFile: File,
val manifest: Model3Json?,
val displayInfo: Cdi3Json?,
val textureFiles: List<File>,
val sidecars: List<Moc3Sidecars.PassThroughSidecar>,
)
/**
* Reads and format-detects one input file. A .model3.json path is accepted as a moc3 input, with
* the MOC3 resolved through the manifest's own file reference.
*
* @param String path The input file path.
* @return LoadedInput The loaded, format-branched input.
*/
internal fun loadInput(path: String): LoadedInput {
val inputFile = File(path)
if (!inputFile.isFile) {
throw CliUsageException("No such file: $path")
}
if (inputFile.name.lowercase(Locale.ROOT).endsWith(".model3.json")) {
val manifest = Moc3.readModel3(inputFile.readText())
val mocFile = File(inputFile.parentFile, manifest.fileReferences.moc)
if (!mocFile.isFile) {
throw CliUsageException("Manifest references a missing MOC3: ${mocFile.path}")
}
return loadMoc3(mocFile, manifestFile = inputFile, manifest = manifest)
}
val bytes = inputFile.readBytes()
return when (val codec = FormatRegistry.detect(bytes, inputFile.name)) {
Cmo3 -> LoadedInput.Cmo3Input(Cmo3.read(bytes), bytes)
Moc3 -> loadMoc3(inputFile, manifestFile = null, manifest = null)
is ArtReader -> LoadedInput.SourceArtInput(codec.read(bytes), inputFile)
// A flat raster becomes a one-layer document, which is what makes `atlas cover.png` mean
// something rather than being rejected for lacking layers.
is RasterCodec -> LoadedInput.SourceArtInput(rasterToSourceArt(codec.read(bytes), inputFile.nameWithoutExtension), inputFile)
else -> throw CliUsageException("Unsupported input format: $path (expected cmo3, moc3, model3.json, or source artwork)")
}
}
/**
* Loads a moc3 and discovers its family. Without an explicit manifest the sibling
* `<basename>.model3.json` is tried first, then any manifest in the directory whose moc reference
* names this file.
*
* @param File mocFile The .moc3 file.
* @param File? manifestFile The manifest file, when the caller already has it.
* @param Model3Json? manifest The parsed manifest, when the caller already has it.
* @return LoadedInput The moc3 input with its family.
*/
private fun loadMoc3(mocFile: File, manifestFile: File?, manifest: Model3Json?): LoadedInput.Moc3Input {
val document = Moc3.read(mocFile.readBytes())
val resolvedManifestFile =
manifestFile
?: File(mocFile.parentFile, Moc3Sidecars.basenameFor(mocFile.name) + ".model3.json").takeIf { candidate -> candidate.isFile }
?: mocFile.parentFile
?.listFiles { _, name -> name.lowercase(Locale.ROOT).endsWith(".model3.json") }
?.firstOrNull { candidate ->
runCatching { Moc3.readModel3(candidate.readText()).fileReferences.moc == mocFile.name }.getOrDefault(false)
}
val resolvedManifest = manifest ?: resolvedManifestFile?.let { file -> Moc3.readModel3(file.readText()) }
if (resolvedManifest == null) {
return LoadedInput.Moc3Input(document, Moc3Family(mocFile, null, null, emptyList(), emptyList()))
}
val manifestDirectory = resolvedManifestFile!!.parentFile
val references = resolvedManifest.fileReferences
// Manifest reference first, then the sibling-by-basename fallback the app's document loader
// uses - a model3 without a DisplayInfo entry otherwise converts nameless, and the export then
// writes parameter ids where Cubism expects display names.
val displayInfo =
listOfNotNull(references.displayInfo, "${mocFile.nameWithoutExtension}.cdi3.json")
.distinct()
.firstNotNullOfOrNull { reference ->
File(manifestDirectory, reference)
.takeIf { file -> file.isFile }
?.let { file -> runCatching { Moc3.readCdi3(file.readText()) }.getOrNull() }
}
val textureFiles = references.textures.map { reference -> File(manifestDirectory, reference) }
val sidecars =
buildList {
fun passThrough(kind: Moc3Sidecars.SidecarKind, reference: String?) {
val file = reference?.let { relative -> File(manifestDirectory, relative) } ?: return
if (file.isFile) {
add(Moc3Sidecars.PassThroughSidecar(kind, file.name, file.readText()))
}
}
passThrough(Moc3Sidecars.SidecarKind.Physics, references.physics)
passThrough(Moc3Sidecars.SidecarKind.Pose, references.pose)
passThrough(Moc3Sidecars.SidecarKind.UserData, references.userData)
}
return LoadedInput.Moc3Input(document, Moc3Family(mocFile, resolvedManifest, displayInfo, textureFiles, sidecars))
}
/**
* Imports a loaded input to the runtime PuppetModel - the exact import path the editor uses.
*
* A MOC3-origin puppet gets restMeshesToCanvasSpace (its rest meshes arrive in parent-deformer
* space); a CMO3-origin one authors directly in canvas pixels and must NOT be rebased.
*
* @param LoadedInput loaded The loaded input.
* @return PuppetModel The imported puppet, in canvas space.
*/
internal fun importPuppet(loaded: LoadedInput): PuppetModel =
when (loaded) {
is LoadedInput.Cmo3Input -> Cmo3Import.fromModelSource(loaded.model.root as CModelSource)
is LoadedInput.Moc3Input -> restMeshesToCanvasSpace(Moc3Import.fromMocDocument(loaded.document, loaded.family.displayInfo))
is LoadedInput.SourceArtInput ->
throw CliUsageException(
"${loaded.file.name} is source artwork, which carries no rig; try `atlas` (a source-art to " +
"PuppetModel bridge is pipeline Phase E and does not exist yet)",
)
}
/**
* One command line split into positionals, boolean flags, and valued options.
*
* @property List positionals The non-flag arguments, in order.
* @property Set flags The boolean flags present, with their leading dashes.
* @property Map options The `--key=value` options, keyed with their leading dashes.
*/
internal class CliArguments(
val positionals: List<String>,
val flags: Set<String>,
val options: Map<String, String>,
) {
/**
* Reads one valued option as an integer.
*
* @param String name The option name, with its leading dashes.
* @param Int defaultValue The value to use when the option is absent.
* @return Int The parsed value.
*/
fun intOption(name: String, defaultValue: Int): Int {
val raw = options[name] ?: return defaultValue
return raw.toIntOrNull() ?: throw CliUsageException("$name expects a whole number, got '$raw'")
}
}
/**
* Splits a command line, rejecting anything the caller did not declare.
*
* Unknown flags are a usage error rather than being ignored, so a mistyped option cannot silently
* produce output the operator believes was generated some other way.
*
* @param List arguments The subcommand's raw arguments.
* @param Set knownFlags The boolean flags this subcommand accepts, with leading dashes.
* @param Set knownOptions The `--key=value` options this subcommand accepts, with leading dashes.
* @return CliArguments The split command line.
*/
internal fun parseArguments(arguments: List<String>, knownFlags: Set<String>, knownOptions: Set<String>): CliArguments {
val positionals = mutableListOf<String>()
val flags = mutableSetOf<String>()
val options = mutableMapOf<String, String>()
for (argument in arguments) {
if (!argument.startsWith("--")) {
positionals.add(argument)
continue
}
val separatorIndex = argument.indexOf('=')
if (separatorIndex < 0) {
if (argument !in knownFlags) {
throw CliUsageException("unknown flag '$argument'")
}
flags.add(argument)
continue
}
val name = argument.substring(0, separatorIndex)
if (name !in knownOptions) {
throw CliUsageException("unknown option '$name'")
}
options[name] = argument.substring(separatorIndex + 1)
}
return CliArguments(positionals, flags, options)
}
/**
* Formats a float like C's printf %.6g (what dump_model.c prints), so dump output stays diffable
* against the relive harness. Java's %g keeps trailing zeros where C strips them, hence the trim.
*
* @param Float value The value to format.
* @return String The %.6g-formatted text with C's trailing-zero trimming.
*/
internal fun formatSixSignificant(value: Float): String {
val raw = String.format(Locale.ROOT, "%.6g", value.toDouble())
val exponentIndex = raw.indexOfFirst { character -> character == 'e' || character == 'E' }
val mantissa = if (exponentIndex >= 0) raw.substring(0, exponentIndex) else raw
val exponent = if (exponentIndex >= 0) raw.substring(exponentIndex) else ""
val trimmed = if (mantissa.contains('.')) mantissa.trimEnd('0').trimEnd('.') else mantissa
return trimmed + exponent
}
@@ -0,0 +1,172 @@
package org.umamo.cli
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.moc3.Moc3
import org.umamo.format.png.PngCodec
import org.umamo.interop.ExportReport
import org.umamo.interop.cmo3.Cmo3Conversion
import org.umamo.interop.cmo3.cmo3AtlasPages
import org.umamo.interop.describeExportNotice
import org.umamo.interop.moc3.Moc3Sidecars
import org.umamo.render.PuppetTextures
import org.umamo.render.UndecodablePagePolicy
import org.umamo.render.buildPuppetTextures
import org.umamo.render.canvasToParentSpaceFor
import org.umamo.render.encodeAtlasPng
import org.umamo.render.withTexturePagesFrom
import java.io.File
import java.util.Locale
import kotlin.random.Random
/*
* The convert subcommand: cmo3/moc3 resaves and cross-format conversions, replacing the old
* Cmo3ResaveDumpTest -Dcmo3.resave workflow.
*/
/**
* Runs `convert <in> <out>`, picking the direction from the input's detected format and the output
* path's extension.
*
* @param List arguments The subcommand's arguments.
* @return Int The exit code.
*/
internal fun runConvert(arguments: List<String>): Int {
if (arguments.size != 2) {
throw CliUsageException("Usage: convert <in> <out>")
}
val loaded = loadInput(arguments[0])
val outputFile = File(arguments[1])
val outputExtension = outputFile.name.substringAfterLast('.', "").lowercase(Locale.ROOT)
outputFile.parentFile?.mkdirs()
when {
loaded is LoadedInput.Cmo3Input && outputExtension == "cmo3" -> {
// An unedited graph re-emits its main.xml byte-identically; only the CAFF wrapper differs.
Cmo3.write(loaded.model, outputFile)
println("Resaved cmo3 -> ${outputFile.path} (${outputFile.length()} bytes)")
}
loaded is LoadedInput.Moc3Input && outputExtension == "moc3" -> {
outputFile.writeBytes(Moc3.write(loaded.document))
println("Rebaked moc3 -> ${outputFile.path} (${outputFile.length()} bytes)")
println("Note: a rebake is a fresh synthesis, NOT byte-identical to the source by design")
}
loaded is LoadedInput.Cmo3Input && outputExtension == "moc3" -> {
convertCmo3ToMoc3Family(loaded, outputFile)
}
loaded is LoadedInput.Moc3Input && outputExtension == "cmo3" -> {
convertMoc3ToCmo3(loaded, outputFile)
}
else -> throw CliUsageException("Unsupported conversion: ${arguments[0]} -> ${outputFile.name}")
}
return 0
}
/**
* Lowers a CMO3 document to the full MOC3 family (moc3 + model3.json + cdi3.json + atlas textures)
* next to [outputFile].
*
* The two mandatory pre-steps mirror the app's own export path: the puppet's drawables arrive on
* the -1 texture-page sentinel (CMO3 binds textures through the layered-art web, not a page index),
* so withTexturePagesFrom must land real pages before the lowering can name them.
*
* @param LoadedInput.Cmo3Input loaded The cmo3 input.
* @param File outputFile The target .moc3 path; the family lands beside it.
*/
private fun convertCmo3ToMoc3Family(loaded: LoadedInput.Cmo3Input, outputFile: File) {
val basename = Moc3Sidecars.basenameFor(outputFile.name)
val importedPuppet = importPuppet(loaded)
val modelSource = (loaded.model.root as org.umamo.format.cmo3.model.custom.CModelSource)
val pageSet = cmo3AtlasPages(modelSource) { imageResource -> loaded.model.extractLayerPng(imageResource) }
// Skip matches the editor's CMO3 loader: a page that will not decode drops rather than failing the
// whole conversion, and Skip never returns null, so the fallback is unreachable.
val textures =
buildPuppetTextures(
pageSet.pageBytes,
pageSet.atlasIndexByDrawableId,
pageSet.premultipliedAlpha,
UndecodablePagePolicy.Skip,
) ?: PuppetTextures(emptyList(), emptyMap(), pageSet.premultipliedAlpha)
val puppet = withTexturePagesFrom(importedPuppet, textures)
val pages =
textures.atlases.mapIndexed { pageIndex, atlas ->
Moc3Sidecars.AtlasPage(
fileName = String.format(Locale.ROOT, "%s.%d/texture_%02d.png", basename, atlas.width, pageIndex),
bytes = encodeAtlasPng(atlas),
)
}
val bundle =
Moc3Sidecars.bundle(
puppet = puppet,
basename = basename,
pages = pages,
canvasToParentSpace = canvasToParentSpaceFor(puppet),
)
// Overwrites without confirmation.
val outputDirectory = outputFile.parentFile ?: File(".")
for (bundleFile in bundle.files) {
val target = File(outputDirectory, bundleFile.name)
target.parentFile?.mkdirs()
target.writeBytes(bundleFile.bytes)
println("Wrote ${target.path} (${bundleFile.bytes.size} bytes)")
}
reportNotices(bundle.report)
}
/**
* Synthesizes a fresh CMO3 from a MOC3-origin document. The atlas pages come from the manifest's
* texture files; without a manifest the conversion proceeds textureless with a warning. A
* MissingSourceArt notice is always reported - the pages are atlas copies, not the original
* layered source art.
*
* @param LoadedInput.Moc3Input loaded The moc3 input with its discovered family.
* @param File outputFile The target .cmo3 path.
*/
private fun convertMoc3ToCmo3(loaded: LoadedInput.Moc3Input, outputFile: File) {
val puppet = importPuppet(loaded)
val presentTextureFiles = loaded.family.textureFiles.filter { textureFile -> textureFile.isFile }
if (loaded.family.manifest == null) {
System.err.println("Warning: no model3.json manifest found beside ${loaded.family.mocFile.name}; converting textureless")
} else if (presentTextureFiles.size < loaded.family.textureFiles.size) {
System.err.println("Warning: ${loaded.family.textureFiles.size - presentTextureFiles.size} manifest texture(s) missing on disk")
}
val pages =
presentTextureFiles.map { textureFile ->
val pngBytes = textureFile.readBytes()
val decoded = PngCodec.read(pngBytes)
Cmo3Conversion.AtlasPage(pngBytes = pngBytes, width = decoded.width, height = decoded.height)
}
val result =
Cmo3Conversion.freshCmo3(
puppet = puppet,
pages = pages,
pageIndexByDrawableId = loaded.document.artMeshes.associate { artMesh -> artMesh.id to artMesh.textureIndex },
modelName = outputFile.name.removeSuffix(".cmo3"),
nowMillis = System.currentTimeMillis(),
obfuscateKey = Random.nextInt(),
)
// Overwrites without confirmation.
Cmo3.write(result.model, outputFile)
println("Wrote ${outputFile.path} (${outputFile.length()} bytes)")
reportNotices(result.report)
}
/**
* Prints an export report's notices to stderr - advisory, never fatal. Each line is the same one the
* editor's log carries for that notice, so a report reads alike whichever tool wrote the file.
*
* @param ExportReport report The lowering's report.
*/
private fun reportNotices(report: ExportReport) {
if (report.isEmpty) {
return
}
System.err.println("Export notices (${report.notices.size}):")
for (notice in report.notices) {
System.err.println(" ${describeExportNotice(notice)}")
}
}
@@ -0,0 +1,94 @@
package org.umamo.cli
import org.umamo.interop.EntityDiff
import org.umamo.interop.GlueDiff
import org.umamo.interop.diffPuppetModels
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.ParameterGroupId
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PartId
/*
* The diff subcommand: the semantic per-entity difference between two models, through the same
* diffPuppetModels the CMO3 export reconcile dispatches on.
*/
/**
* Runs `diff <a> <b>`: imports both files (either format, both normalized to canvas space by the
* import path) and prints the per-category difference. Exit stays 0 either way - a diff is a
* report, not a failure.
*
* @param List arguments The subcommand's arguments.
* @return Int The exit code.
*/
internal fun runDiff(arguments: List<String>): Int {
if (arguments.size != 2) {
throw CliUsageException("Usage: diff <a> <b>")
}
val baseline = importPuppet(loadInput(arguments[0]))
val edited = importPuppet(loadInput(arguments[1]))
val diff = diffPuppetModels(baseline, edited)
if (diff.isEmpty) {
println("identical")
return 0
}
printCategory("parameters", diff.parameters)
printCategory("parameterGroups", diff.parameterGroups)
printCategory("parts", diff.parts)
printCategory("deformers", diff.deformers)
printCategory("drawables", diff.drawables)
if (diff.glues.isNotEmpty()) {
println("[glues]")
for (glueDiff in diff.glues) {
val key = "${glueDiff.meshA.raw}~${glueDiff.meshB.raw}#${glueDiff.ordinal}"
when (glueDiff) {
is GlueDiff.Created -> println("+ $key")
is GlueDiff.Deleted -> println("- $key")
is GlueDiff.Changed -> println("~ $key ${glueDiff.fields.sorted()}")
}
}
}
if (diff.document.isNotEmpty()) {
println("[document]")
println("~ ${diff.document.sorted()}")
}
return 0
}
/**
* Prints one entity category's diffs: `+ id` created, `- id` deleted, `~ id [FIELDS]` changed.
*
* @param String label The category heading.
* @param List diffs The category's entries (skipped entirely when empty).
*/
private fun <TId, TField : Comparable<TField>> printCategory(label: String, diffs: List<EntityDiff<TId, TField>>) {
if (diffs.isEmpty()) {
return
}
println("[$label]")
for (entityDiff in diffs) {
when (entityDiff) {
is EntityDiff.Created -> println("+ ${formatEntityId(entityDiff.id)}")
is EntityDiff.Deleted -> println("- ${formatEntityId(entityDiff.id)}")
is EntityDiff.Changed -> println("~ ${formatEntityId(entityDiff.id)} ${entityDiff.fields.sorted()}")
}
}
}
/**
* The bare id string of a typed entity id - the value-class toString ("PartId(raw=...)") is noise
* in a report meant for humans and diff scripts.
*
* @param Any? id The typed entity id.
* @return String The raw id text.
*/
private fun formatEntityId(id: Any?): String =
when (id) {
is ParameterId -> id.raw
is ParameterGroupId -> id.raw
is PartId -> id.raw
is DeformerId -> id.raw
is DrawableId -> id.raw
else -> id.toString()
}
@@ -0,0 +1,249 @@
package org.umamo.cli
import org.umamo.format.art.SourceLayerKind
import org.umamo.format.art.analyzeAlpha
import org.umamo.format.cmo3.Cmo3Model
import org.umamo.format.cmo3.caff.CaffArchive
import org.umamo.format.cmo3.serialize.ModelDocument
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.moc.MocCodec
import org.umamo.format.moc3.moc.Section
import org.umamo.runtime.model.PuppetModel
/*
* The dump subcommand: human-readable (and, for MOC3, dump_model.c-diffable) file contents.
*/
/**
* Runs `dump <file> [--sections] [--xml] [--puppet]`.
*
* @param List arguments The subcommand's arguments.
* @return Int The exit code.
*/
internal fun runDump(arguments: List<String>): Int {
val flags = arguments.filter { argument -> argument.startsWith("--") }.toSet()
val positionals = arguments.filterNot { argument -> argument.startsWith("--") }
val unknownFlags = flags - setOf("--sections", "--xml", "--puppet")
if (unknownFlags.isNotEmpty()) {
throw CliUsageException("unknown dump flag(s): ${unknownFlags.joinToString(", ")}")
}
if (positionals.size != 1) {
throw CliUsageException("usage: dump <file> [--sections] [--xml] [--puppet]")
}
val loaded = loadInput(positionals[0])
when (loaded) {
is LoadedInput.Moc3Input -> {
if ("--xml" in flags) {
throw CliUsageException("--xml applies to cmo3 input only")
}
if ("--sections" in flags) {
dumpMoc3Sections(loaded)
} else {
dumpMoc3Document(loaded.document)
}
}
is LoadedInput.Cmo3Input -> {
if ("--sections" in flags) {
throw CliUsageException("--sections applies to moc3 input only")
}
if ("--xml" in flags) {
dumpCmo3Xml(loaded.model)
return 0
}
dumpCmo3Overview(loaded.model)
}
is LoadedInput.SourceArtInput -> {
if ("--sections" in flags || "--xml" in flags) {
throw CliUsageException("--sections and --xml do not apply to source artwork")
}
dumpSourceArt(loaded)
}
}
if ("--puppet" in flags) {
dumpPuppetSummary(importPuppet(loaded))
}
return 0
}
/**
* The MOC3 semantic summary, mirroring dump_model.c's static line grammar (`P`/`T`/`D` records) so
* the relive harness's diff scripts can consume it. Runtime-evaluated columns (posed draw/render
* order, evaluated opacities, vertex-position hashes) are deliberately absent - this dumps the
* static rig, not a revived core.
*
* @param MocDocument document The decoded moc.
*/
private fun dumpMoc3Document(document: MocDocument) {
println("# MOC3 version=${document.version.byteValue}")
document.canvas?.let { canvas ->
val size = "${formatSixSignificant(canvas.width)},${formatSixSignificant(canvas.height)}"
val origin = "${formatSixSignificant(canvas.originX)},${formatSixSignificant(canvas.originY)}"
println("# canvas size=$size origin=$origin ppu=${formatSixSignificant(canvas.pixelsPerUnit)}")
}
println(
"# counts parameters=${document.parameters.size} parts=${document.parts.size} " +
"drawables=${document.artMeshes.size} deformers=${document.deformers.size} " +
"glues=${document.glues.size} groups=${document.renderOrderGroups.size} " +
"bindings=${document.bindings.size} blendShapes=${document.blendShapes.size} " +
"offscreens=${document.offscreens.size}",
)
println("[parameters]")
document.parameters.forEachIndexed { parameterIndex, parameter ->
println(
"P $parameterIndex id=${parameter.id} type=${parameter.type?.number ?: -1} " +
"min=${formatSixSignificant(parameter.minimumValue)} max=${formatSixSignificant(parameter.maximumValue)} " +
"def=${formatSixSignificant(parameter.defaultValue)} repeat=${if (parameter.repeats) 1 else 0}",
)
}
println("[parts]")
document.parts.forEachIndexed { partIndex, part ->
println("T $partIndex id=${part.id} parent=${part.parentPartIndex}")
}
println("[drawables]")
document.artMeshes.forEachIndexed { meshIndex, artMesh ->
println(
"D $meshIndex id=${artMesh.id} cflag=0x${(artMesh.constantFlags and 0xFF).toString(16).padStart(2, '0')} " +
"tex=${artMesh.textureIndex} part=${artMesh.parentPartIndex} vtx=${artMesh.vertexCount} " +
"idx=${artMesh.triangleIndices.size} masks=${artMesh.maskDrawableIndices.size}",
)
}
}
/**
* The MOC3 container tier: version, CountInfo, and per-section presence with element counts.
*
* @param LoadedInput.Moc3Input loaded The moc3 input (re-read at the container tier).
*/
private fun dumpMoc3Sections(loaded: LoadedInput.Moc3Input) {
val container = MocCodec.read(loaded.family.mocFile.readBytes())
println("# MOC3 version=${container.versionByte} sections=${container.sectionCount} bigEndian=${container.isBigEndian}")
println("# countInfo ${container.countInfo.joinToString(",")}")
var presentCount = 0
for (section in Section.entries) {
if (!container.sections.isPresent(section)) {
continue
}
presentCount++
println("S ${section.name} count=${container.sections.elementCount(section)}")
}
println("# sections present=$presentCount modeled=${Section.entries.size}")
}
/**
* The CMO3 overview: target version, the CAFF entry table, the embedded image resources, and the
* parsed main.xml prologue summary.
*
* @param Cmo3Model model The read model.
*/
private fun dumpCmo3Overview(model: Cmo3Model) {
val archive = model.archive
println("# CMO3 targetVersionNo=${model.targetVersionNo ?: "-"}")
println(
"# caff formatVersion=${archive.formatVersion.joinToString(".")} " +
"archiveVersion=${archive.archiveVersion.joinToString(".")} " +
"obfuscateKey=${archive.obfuscateKey}",
)
println("[entries]")
archive.entries.forEachIndexed { entryIndex, entry ->
println(
"E $entryIndex path=${entry.path} tag=${entry.tag} size=${entry.content.size} " +
"compression=${entry.compression} obfuscated=${if (entry.obfuscated) 1 else 0}",
)
}
println("[images]")
model.imageResources().forEachIndexed { imageIndex, resource ->
val pngSize = model.extractLayerPng(resource)?.size ?: 0
println("I $imageIndex type=${resource.type} width=${resource.width} height=${resource.height} pngBytes=$pngSize")
}
val mainXml = archive.firstByTag(CaffArchive.TAG_MAIN_XML)
if (mainXml != null) {
// sharedElements/mainElements are JDOM-typed and JDOM stays :format-internal; the class-version
// table and import list are the useful prologue summary anyway.
val parsed = ModelDocument.parse(mainXml.content)
println("[xml]")
println("# versions ${parsed.versions.entries.joinToString(" ") { (className, versionNumber) -> "$className=$versionNumber" }}")
println("# imports ${parsed.imports.joinToString(" ")}")
}
}
/**
* Writes the decompressed main.xml to stdout byte-for-byte, so a shell redirect round-trips it.
* CaffEntry.content is already inflated and deobfuscated by the CAFF read.
*
* @param Cmo3Model model The read model.
*/
private fun dumpCmo3Xml(model: Cmo3Model) {
val mainXml =
model.archive.firstByTag(CaffArchive.TAG_MAIN_XML)
?: throw IllegalStateException("archive has no main_xml entry")
System.out.write(mainXml.content)
System.out.flush()
}
/**
* The imported-puppet summary: entity counts and the parameter table - the exact import path the
* convert command lowers from, so a suspect conversion can be inspected at this tier first.
*
* @param PuppetModel puppet The imported puppet.
*/
private fun dumpPuppetSummary(puppet: PuppetModel) {
println("[puppet]")
println(
"# counts parameters=${puppet.parameters.size} parts=${puppet.parts.size} " +
"deformers=${puppet.deformers.size} drawables=${puppet.drawables.size} glues=${puppet.glues.size}",
)
println(
"# canvas ${formatSixSignificant(puppet.canvasWidth)}x${formatSixSignificant(puppet.canvasHeight)} " +
"origin=${formatSixSignificant(puppet.worldOriginX)},${formatSixSignificant(puppet.worldOriginZ)} " +
"target=${puppet.runtimeTarget.name}",
)
puppet.parameters.forEachIndexed { parameterIndex, parameter ->
println(
"P $parameterIndex id=${parameter.id.raw} min=${formatSixSignificant(parameter.min)} " +
"max=${formatSixSignificant(parameter.max)} def=${formatSixSignificant(parameter.default)}",
)
}
}
/**
* The source-artwork summary: canvas, folder attributes, and one line per layer.
*
* The layer inventory a PSD/CLIP/KRA reader produces has had no way to be seen until now, which is
* the same gap the atlas command closes on the packing side - this is what you read to judge whether
* a pack skipped the layers it should have. The alpha column is the packer's own view: the trimmed
* opaque bounds, or `empty` for a layer with no opaque pixel (which never reaches a page).
*
* @param LoadedInput.SourceArtInput loaded The loaded artwork document.
*/
private fun dumpSourceArt(loaded: LoadedInput.SourceArtInput) {
val art = loaded.art
val rasterLayerCount = art.layers.count { layer -> layer.kind == SourceLayerKind.Raster }
println("[artwork] ${loaded.file.name}")
println("# canvas ${art.widthPx}x${art.heightPx}")
println("# counts layers=${art.layers.size} raster=$rasterLayerCount groups=${art.groups.size}")
art.groups.forEach { group ->
println(
"G path=${group.path} name=${group.name} vis=${if (group.visible) 1 else 0} " +
"op=${formatSixSignificant(group.opacity)} blend=${group.blend} " +
"clip=${if (group.clipped) 1 else 0} through=${if (group.passThrough) 1 else 0}",
)
}
art.layers.forEachIndexed { layerIndex, layer ->
val trimmed = layer.analyzeAlpha(contourEpsilon = 0f)
val alphaColumn =
if (trimmed == null) {
"empty"
} else {
"${trimmed.opaqueBounds.width}x${trimmed.opaqueBounds.height}" +
"+${trimmed.opaqueBounds.left}+${trimmed.opaqueBounds.top}"
}
println(
"L $layerIndex order=${layer.order} kind=${layer.kind} id=${layer.id.raw} name=${layer.name} " +
"at=${layer.bounds.left},${layer.bounds.top} size=${layer.bounds.width}x${layer.bounds.height} " +
"alpha=$alphaColumn op=${formatSixSignificant(layer.opacity)} blend=${layer.blend} " +
"vis=${if (layer.visible) 1 else 0} clip=${if (layer.clipped) 1 else 0} group=${layer.groupPath}",
)
}
}
@@ -0,0 +1,69 @@
package org.umamo.cli
import java.io.File
import java.util.Locale
/*
* The extract subcommand: unpack a cmo3's CAFF archive into loose files - the plaintext main.xml
* plus every embedded layer PNG.
*/
/**
* Runs `extract <file> [<directory>]`.
*
* The entries land in a NEW subdirectory named after the model, created under the given directory
* (default: the input file's own directory) - `extract Model.cmo3 test/work/` writes into
* `test/work/Model/`. The subdirectory is deliberate accident insurance: extraction never mixes
* its output into a folder that already holds other files.
*
* @param List arguments The subcommand's arguments.
* @return Int The exit code.
*/
internal fun runExtract(arguments: List<String>): Int {
val positionals = arguments.filterNot { argument -> argument.startsWith("--") }
if (arguments.size != positionals.size || positionals.isEmpty() || positionals.size > 2) {
throw CliUsageException("Usage: extract <file> [<directory>]")
}
val loaded = loadInput(positionals[0])
if (loaded !is LoadedInput.Cmo3Input) {
throw CliUsageException("Extract applies to cmo3 input only")
}
val inputFile = File(positionals[0])
val modelName =
inputFile.name.let { fileName ->
if (fileName.lowercase(Locale.ROOT).endsWith(".cmo3")) fileName.dropLast(".cmo3".length) else fileName
}
val parentDirectory = if (positionals.size == 2) File(positionals[1]) else (inputFile.parentFile ?: File("."))
val extractionDirectory = File(parentDirectory, modelName)
if (extractionDirectory.exists()) {
System.err.println("Note: ${extractionDirectory.path} already exists; its matching files will be overwritten.")
}
extractionDirectory.mkdirs()
val archive = loaded.model.archive
val writtenNames = HashSet<String>()
archive.entries.forEachIndexed { entryIndex, entry ->
// Entry paths are archive data: guard against traversal and collisions rather than trusting them.
val safeName = entry.path.ifBlank { "entry_$entryIndex" }
val uniqueName = if (writtenNames.add(safeName)) safeName else "entry_${entryIndex}_$safeName"
val target = File(extractionDirectory, uniqueName)
if (!target.canonicalFile.toPath().startsWith(extractionDirectory.canonicalFile.toPath())) {
throw IllegalStateException("Archive entry escapes the extraction directory: ${entry.path}")
}
target.parentFile?.mkdirs()
// CaffEntry.content is already inflated and deobfuscated, so main.xml lands as plaintext.
target.writeBytes(entry.content)
println("Extracted ${target.path} (${entry.content.size} bytes)")
}
if (archive.preview.present) {
val previewTarget = File(extractionDirectory, "preview.png")
if (writtenNames.contains("preview.png")) {
System.err.println("Note: An archive entry already claimed preview.png; the CAFF preview image was skipped.")
} else {
previewTarget.writeBytes(archive.preview.png!!)
println("Extracted ${previewTarget.path} (${archive.preview.png!!.size} bytes, CAFF preview)")
}
}
println("Extracted ${archive.entries.size} entries into ${extractionDirectory.path}")
return 0
}
@@ -0,0 +1,113 @@
package org.umamo.cli
import kotlin.system.exitProcess
/*
* The Umamo diagnostic CLI: dump / extract / atlas / convert / diff over cmo3, moc3, and source
* artwork files.
*
* Replaces the diagnostic-tests-in-disguise workflow (Cmo3ResaveDumpTest's -Dcmo3.resave, ad-hoc
* probe printlns) with a proper operator tool. Data goes to stdout, diagnostics to stderr; exit 0
* on success, 1 on a command failure, 2 on a usage error.
*/
private const val USAGE = """Umamo diagnostic CLI
Usage (via Gradle; -q suppresses Gradle's own build output, leaving only this tool's):
./gradlew -q :cli:run --args="dump <file> [--sections] [--xml] [--puppet]"
./gradlew -q :cli:run --args="extract <file> [<directory>]"
./gradlew -q :cli:run --args="atlas <file> [<directory>] [options]"
./gradlew -q :cli:run --args="convert <in> <out>"
./gradlew -q :cli:run --args="diff <a> <b>"
Commands:
dump <file> Print a cmo3/moc3/artwork file's contents. MOC3 defaults to printing
a static rig summary. CMO3 defaults to the archive entry table plus
the parsed main.xml overview. Source artwork(PSD, CLIP, KRA, or a
flat raster) prints its canvas, folders, and per-layer inventory with
each layer's trimmed opaque bounds.
--sections MOC3 container tier: per-section presence and counts.
--xml CMO3 only: the decompressed main.xml, byte-for-byte.
--puppet Either format: import to a PuppetModel and summarize.
extract <file> [<directory>]
Unpack a cmo3's archive into loose files: The plaintext main.xml plus
every embedded layer PNG. Files write to a NEW subdirectory named
after the model, created under <directory> (Default: The file's own
directory) - `extract Model.cmo3 test/work/` writes test/work/Model/.
atlas <file> [<directory>]
Pack a source artwork document(PSD, CLIP, KRA, or a flat raster) into
texture atlas pages. Writes page_NN.png plus placements.txt to a NEW
subdirectory named after the input, then reads every packed tile back
out of its page and fails if any byte differs. Layers with no opaque
pixels, or too large for a page, are reported rather than dropped.
--page-size=N Page side to pack against (Default: 4096).
--gutter=N Transparent spacing around every tile (Default: 2).
--extrude=N Edge pixels replicated into the gutter (Default: 2).
--rotate Allow quarter-turning tiles to pack tighter.
--visible-only Skip layers hidden by their own or a folder's eye.
--no-shrink Keep full --page-size pages instead of cropping.
--preview Also write preview.png: the canvas recomposited
from the packed pages (Source-over; blend modes
and layer opacity ignored).
convert <in> <out>
Direction by input format and output extension:
cmo3 -> cmo3 Resave (An unedited main.xml will reemit byte-identical.)
moc3 -> moc3 Rebake (Fresh synthesis, NOT byte-identical by design.)
cmo3 -> moc3 Full family: moc3 + model3.json + cdi3.json + textures
moc3 -> cmo3 Fresh-graph synthesis (Cubism can open it; the source
art pages are atlas copies, so a MissingSourceArt
notice is always reported.)
A moc3 input may also be given as its .model3.json manifest; sibling
sidecars (model3/cdi3/physics3/pose3/userdata3) are discovered by
the manifest's own file references.
diff <a> <b> Import both files (either format) and print the semantic per-entity
difference.
help This text."""
/**
* The CLI entry point: dispatches to a subcommand and converts its outcome to an exit code.
*
* @param Array args The raw command-line arguments (Gradle's --args, split).
*/
fun main(args: Array<String>) {
val exitCode = runCli(args.toList())
if (exitCode != 0) {
exitProcess(exitCode)
}
}
/**
* Runs one CLI invocation. Split from main so the dispatch stays testable without exiting the JVM.
*
* @param List arguments The command line: a verb followed by its positionals and flags.
* @return Int The process exit code (0 success, 1 failure, 2 usage error).
*/
internal fun runCli(arguments: List<String>): Int {
if (arguments.isEmpty() || arguments[0] == "help" || arguments[0] == "--help") {
println(USAGE)
return if (arguments.isEmpty()) 2 else 0
}
return try {
when (arguments[0]) {
"dump" -> runDump(arguments.drop(1))
"extract" -> runExtract(arguments.drop(1))
"atlas" -> runAtlas(arguments.drop(1))
"convert" -> runConvert(arguments.drop(1))
"diff" -> runDiff(arguments.drop(1))
else -> {
System.err.println("unknown command '${arguments[0]}'")
System.err.println(USAGE)
2
}
}
} catch (usageError: CliUsageException) {
System.err.println(usageError.message)
2
} catch (failure: Exception) {
System.err.println("error: ${failure.message ?: failure::class.simpleName}")
1
}
}
/** A malformed invocation - reported as usage (exit 2) rather than a command failure (exit 1). */
internal class CliUsageException(message: String) : Exception(message)
+223
View File
@@ -0,0 +1,223 @@
// :desktop (app/desktop) — desktop entrypoint (Compose Desktop + LWJGL viewport interop).
// :desktop — デスクトップ起動点(Compose Desktop + LWJGL ビューポート連携)。
plugins {
alias(libs.plugins.kotlinMultiplatform)
alias(libs.plugins.composeMultiplatform)
alias(libs.plugins.composeCompiler)
}
// EN: Resolve which platform's natives this build bundles (default: the host; override with
// -Pumamo.target=<os>-<arch>, e.g. windows-x64 to cross-build from WSL2 Linux). The shared script
// also drives :render so both modules agree; it exposes its result via extra properties. See
// gradle/build-target.gradle.kts for the full rationale and the cross-build recipe.
// JA: 同梱するネイティブの対象プラットフォームを解決する(既定はホスト、-Pumamo.target で上書き)。
apply(from = rootProject.file("gradle/build-target.gradle.kts"))
val buildTarget = extra["umamoBuildTarget"] as String
val lwjglNatives = extra["umamoLwjglNatives"] as String
// Resolve the application version from ProjectInfo.kt (see gradle/project-version.gradle.kts) so
// the packaged artifacts never drift from what the About dialog shows.
apply(from = rootProject.file("gradle/project-version.gradle.kts"))
val umamoVersion = extra["umamoVersion"] as String
val umamoVersionNumeric = extra["umamoVersionNumeric"] as String
// The .uma document type every OS registration names. OsAssociationFilesTest holds this script, the Android
// manifest, and the freedesktop files to the codec's own Uma.MIME_TYPE, so the four cannot drift apart.
val umaMimeType = "application/vnd.umamo.uma+zip"
val umaExtension = "uma"
val umaDescription = "Umamo Document"
kotlin {
jvmToolchain(21)
jvm()
sourceSets {
jvmMain {
dependencies {
// EN: Compose Desktop's per-target artifact bundles the matching Skiko native (a
// .so/.dll/.dylib). buildTarget is exactly the artifact's "<os>-<arch>" suffix, so
// `desktop-jvm-$buildTarget` selects the right one — on the host this is what
// `compose.desktop.currentOs` resolves to, so the default path is unchanged. Direct
// coordinate (not the `compose.desktop.<target>` accessor) because those accessors are
// deprecated in CMP 1.11 — same migration the version catalog already made for the
// other compose.* artifacts (see libs.versions.toml).
// JA: 対象プラットフォームの Skiko ネイティブを含む Compose Desktop 依存を直接座標で選ぶ。
implementation("org.jetbrains.compose.desktop:desktop-jvm-$buildTarget:${libs.versions.composeMultiplatform.get()}")
// Compose resources: the desktop menu bar localizes against :ui's EN/JA catalogs via
// stringResource(Res.string.*); :ui exposes it as implementation, so declare it here too.
implementation(libs.compose.components.resources)
implementation(project(":ui"))
implementation(project(":runtime"))
// Editing core: the per-document EditorSession the desktop host creates and the
// Selection / EditorMode model the viewport pick reads (used directly in jvmMain).
implementation(project(":edit"))
implementation(project(":render"))
implementation(project(":settings"))
implementation(project(":storage"))
// Explicit (also transitive via :runtime) — Document loading calls FormatRegistry/Cmo3 directly.
implementation(project(":format"))
// JNA: a tiny Win32 FFI for desktop window chrome (the DWM title-bar caption tint).
// Already on the runtime classpath via FileKit; declared here so jvmMain compiles
// against com.sun.jna.* directly. No-op off Windows — the call is OS-guarded.
implementation(libs.jna)
// LWJGL GL for the offscreen viewport renderer; BOM keeps module versions aligned.
implementation(project.dependencies.platform(libs.lwjgl.bom))
implementation(libs.lwjgl.core)
implementation(libs.lwjgl.opengl)
// GLFW: a hidden-window GL context for the OFFSCREEN viewport renderer. The puppet is
// rendered to an FBO and shown as a lightweight Compose Image (not a heavyweight AWT
// canvas), so Compose menus/overlays/gizmos layer over it correctly on every platform.
implementation(libs.lwjgl.glfw)
runtimeOnly("org.lwjgl:lwjgl::$lwjglNatives")
runtimeOnly("org.lwjgl:lwjgl-opengl::$lwjglNatives")
runtimeOnly("org.lwjgl:lwjgl-glfw::$lwjglNatives")
}
}
jvmTest {
dependencies {
implementation(kotlin("test"))
}
}
}
}
// Compose Desktop's packaging/run DSL. `:desktop:run` launches the editor.
compose.desktop {
application {
mainClass = "org.umamo.editor.desktop.MainKt"
// Everything in this jvmArgs list is baked into the PACKAGED launcher too — the plugin
// hands application.jvmArgs straight to jpackage as --java-options, which end up in
// umamo.cfg. So only put things here that are true for a shipped build. The corpus-preview
// override, a developer affordance pointing at a gitignored absolute host path, is set on
// `:desktop:run` alone at the bottom of this file.
//
// Decoding the 8192² atlas to RGBA is transiently heavy (~0.5 GB); give the preview headroom.
jvmArgs.add("-Xmx16g")
nativeDistributions {
// packageName feeds the uber-jar base name (and any future jpackage installers);
// lowercase matches the project/domain and Linux package conventions.
packageName = "umamo"
// jpackage rejects prerelease suffixes, so installers get the numeric form; the uber jar
// keeps the full ProjectInfo string (below).
packageVersion = umamoVersionNumeric
// Identity metadata. jpackage stamps vendor/description/copyright into the Windows exe
// version resource and the macOS Info.plist, and copies licenseFile into the app image
// — so even an unsigned build says who made it and under what terms.
vendor = "Umamo Project"
description = "Cross-platform 2D puppet modelling editor with Live2D Cubism .cmo3 interop."
copyright = "Copyright (C) Umamo Project contributors. Licensed under the GPL-3.0."
licenseFile.set(rootProject.file("LICENSE"))
// The jlink module set for the bundled runtime. Compose's default is
// [java.base, java.desktop, java.logging, jdk.crypto.ec] and modules(...) APPENDS to
// it rather than replacing it, so these are purely additive. Each is load-bearing,
// and each was traced to the jar that needs it with `jdeps --list-deps`:
// java.instrument — kotlinx-coroutines' AgentPremain debug-probe transformer.
// java.sql — SQLDelight's JdbcSqliteDriver / sqlite-jdbc (CLIP ingest).
// java.xml — JDOM's SAX/JAXP path, i.e. all of CMO3 read/write. Already
// implied (java.desktop requires it transitively), but CMO3 is
// the product; it should not ride on someone else's implication.
// jdk.security.auth — dbus-java, under FileKit's XDG-portal open/save dialogs.
// jdk.unsupported — sun.misc.Unsafe, which LWJGL's MemoryBackendUnsafe* needs.
// Deliberately NOT includeAllModules: that adds ~50 MB per platform to paper over a
// class of bug the release workflow already catches by asserting on the MODULES= line
// of jlink's `release` descriptor. Re-run `:desktop:suggestRuntimeModules` after any
// dependency change and add whatever it names — but note it under-reports, since it
// misses reflective and service-loaded edges (it does not name java.xml).
modules("java.instrument", "java.sql", "java.xml", "jdk.security.auth", "jdk.unsupported")
// App icon per OS. jpackage demands a different container per platform and reads only
// its own host's file, so all three are committed and each is consumed when packaging on
// that OS. These feed createDistributable / the native installers (not the uber jar,
// which carries no icon). Regenerate from the mascot with docs/design/appicon/generate.sh.
//
// The .uma document type (docs/format/UMA.md § 2), declared per OS because that is where the plugin
// puts it. What it does depends on what is being built:
// * macOS: the plugin writes CFBundleDocumentTypes into the app image's own Info.plist, so an
// unpacked Umamo.app is already the handler for .uma - no installer needed.
// * Windows and Linux: the plugin hands it to jpackage as --file-associations, which jpackage
// accepts for INSTALLERS only. It is inert for createDistributable, the only thing a release
// ships today, and takes effect the day an msi / deb is built. Until then Linux registers the
// type per user from the two files under resources/linux (see appResourcesRootDir below).
// The document reuses the application icon until it has one of its own.
windows {
iconFile.set(project.file("icons/umamo.ico"))
fileAssociation(umaMimeType, umaExtension, umaDescription, project.file("icons/umamo.ico"))
}
macOS {
iconFile.set(project.file("icons/umamo.icns"))
fileAssociation(umaMimeType, umaExtension, umaDescription, project.file("icons/umamo.icns"))
// CFBundleIdentifier. Matches :android's applicationId so one reverse-DNS identity
// covers the project on both platforms. Not required for an unsigned app image (the
// plugin only validates it when signing), but jpackage would otherwise derive one
// from the main-class package — and macOS keys preferences and TCC permission grants
// on this string, so changing it later orphans every user's saved state.
bundleID = "org.umamo.editor"
}
linux {
iconFile.set(project.file("icons/umamo.png"))
fileAssociation(umaMimeType, umaExtension, umaDescription, project.file("icons/umamo.png"))
}
// Files copied into the app image beside the jars (lib/app/resources on Linux). resources/linux
// holds the freedesktop shared-mime-info entry and the desktop entry a rigger installs per user to
// make the file manager open .uma with an unpacked Umamo.
appResourcesRootDir.set(project.layout.projectDirectory.dir("resources"))
}
}
}
// OsAssociationFilesTest reads the OS registration files straight from disk - this script, the Android manifest,
// and the two freedesktop files - and holds them to the codec's Uma.MIME_TYPE. None of them is on the test
// classpath, so Gradle does not know the test depends on them: left undeclared, an edit to any one leaves
// jvmTest UP-TO-DATE and the check silently never runs against the change it exists to catch.
val osAssociationFiles =
files(
"resources/linux/umamo-uma.xml",
"resources/linux/umamo.desktop",
"build.gradle.kts",
rootProject.file("app/android/src/main/AndroidManifest.xml"),
)
tasks.withType<Test>().configureEach {
inputs.files(osAssociationFiles).withPropertyName("osAssociationFiles").withPathSensitivity(PathSensitivity.RELATIVE)
}
// `umamo.testCmo3` opens the corpus CMO3 (gitignored; the puppet preview) on launch. It is a
// DEVELOPER affordance carrying an absolute host path, so it must never reach a packaged
// artifact where that path does not exist — hence the run task rather than
// application.jvmArgs, which the plugin forwards to jpackage as --java-options.
//
// Two deliberate choices:
// * withType/matching/configureEach, not tasks.named("run"): the Compose plugin registers its
// tasks inside its own afterEvaluate, so `run` does not exist while this script is being
// evaluated and named() would throw. Same lazy idiom as the uber-jar override below.
// * systemProperty(), not jvmArgs(): the plugin's own configuration action calls
// JavaExec.setJvmArgs() — a REPLACE, not an append. Gradle happens to run that action before
// this one so an appended jvmArg would survive today, but systemProperties is a separate
// collection setJvmArgs never touches, so this holds regardless of action ordering.
// The path is resolved to a val first so the lambda captures a String, not the Project
// (configuration cache).
val runPreviewCmo3Path = rootProject.file("test/corpus/cmo3/EricaTamamo.cmo3").absolutePath
tasks.withType<JavaExec>().matching { execTask -> execTask.name == "run" }
.configureEach {
systemProperty("umamo.testCmo3", runPreviewCmo3Path)
}
// The Compose plugin stamps the uber jar with the HOST os token (its own currentTarget
// detection), which lies when -Pumamo.target cross-resolves the bundled natives — the jar
// CONTENTS already honor buildTarget (Skiko artifact and LWJGL natives above). The plugin
// assigns the name PARTS (appendix/version) directly in its afterEvaluate, after any
// configureEach action, so part-level overrides lose; an explicit archiveFileName replaces the
// derived-from-parts convention outright and wins regardless of assignment order.
//
// Target before version — umamo-<os>-<arch>-<version>.<ext>. Keep that order: it is what the
// release assets are named and what downstream tooling matches on.
tasks.withType<org.gradle.jvm.tasks.Jar>().matching { jarTask -> jarTask.name == "packageUberJarForCurrentOS" }
.configureEach {
archiveFileName.set("umamo-$buildTarget-$umamoVersion.jar")
}
Binary file not shown.
Binary file not shown.

After

Width:  |  Height:  |  Size: 106 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.9 KiB

+29
View File
@@ -0,0 +1,29 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Umamo's document type for the freedesktop shared MIME database.
The magic is the identification probe of docs/format/UMA.md § 2, verbatim: a ZIP whose FIRST entry is a stored
"mimetype" with no extra field, so its content sits at a fixed offset. Nested the way the shared database
declares EPUB and OpenDocument, at their priority. That is above application/zip's own magic (the bare
local-header signature), so a .uma with no extension still reads as a UMA. It is deliberately below 80, the
level at which magic would outrank a file's name: a .uma someone renamed to .zip reads as a ZIP, as a renamed
OpenDocument file does - they asked for the archive.
The README's "Opening .uma files from the file manager" gives the per-user install for an unpacked Umamo.
-->
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
<mime-type type="application/vnd.umamo.uma+zip">
<comment>Umamo Document</comment>
<comment xml:lang="ja">Umamo ドキュメント</comment>
<sub-class-of type="application/zip"/>
<generic-icon name="x-office-drawing"/>
<magic priority="70">
<match type="string" offset="0" value="PK\003\004">
<match type="string" offset="30" value="mimetype">
<match type="string" offset="38" value="application/vnd.umamo.uma+zip"/>
</match>
</match>
</magic>
<glob pattern="*.uma"/>
</mime-type>
</mime-info>
+16
View File
@@ -0,0 +1,16 @@
[Desktop Entry]
Type=Application
Version=1.0
Name=Umamo
GenericName=2D Puppet Modelling Editor
GenericName[ja]=2Dパペット モデリングエディター
Comment=Model 2D puppets in the Live2D Ecosystem
Comment[ja]=Live2Dエコシステムにおける2Dパペットのモデリング
# The launcher is named by PATH: an unpacked archive has no fixed location. Put bin/umamo on the PATH, or
# replace this with its absolute path, then: xdg-desktop-menu install --novendor umamo.desktop
Exec=umamo %f
TryExec=umamo
Icon=umamo
Terminal=false
Categories=Graphics;2DGraphics;
MimeType=application/vnd.umamo.uma+zip;
@@ -0,0 +1,274 @@
package org.umamo.editor.desktop
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.runtime.snapshotFlow
import androidx.compose.ui.window.Window
import androidx.compose.ui.window.application
import io.github.vinceglb.filekit.FileKit
import kotlinx.coroutines.runBlocking
import org.jetbrains.compose.resources.painterResource
import org.jetbrains.compose.resources.stringResource
import org.umamo.editor.desktop.viewport.OffscreenPuppetService
import org.umamo.format.FileRole
import org.umamo.format.FormatRegistry
import org.umamo.runtime.model.ParameterId
import org.umamo.storage.UmamoLog
import org.umamo.storage.desktopAppStorage
import org.umamo.storage.platformFileFromSavedPath
import org.umamo.ui.LocalSettings
import org.umamo.ui.app.EditorApp
import org.umamo.ui.app.HostOpenRequests
import org.umamo.ui.app.rememberDocumentFileFor
import org.umamo.ui.app.rememberEditorSessionFor
import org.umamo.ui.app.rememberExitGuard
import org.umamo.ui.document.Document
import org.umamo.ui.document.DocumentLoad
import org.umamo.ui.document.PuppetDocument
import org.umamo.ui.document.addRecentFile
import org.umamo.ui.document.fileDisplayName
import org.umamo.ui.document.loadDocument
import org.umamo.ui.document.newBlankDocument
import org.umamo.ui.l10n.FALLBACK_LOCALE_TAG
import org.umamo.ui.l10n.LOCALE_SETTINGS_KEY
import org.umamo.ui.l10n.applyAppLocale
import org.umamo.ui.loadAppSettings
import org.umamo.ui.resources.Res
import org.umamo.ui.resources.app_icon
import org.umamo.ui.resources.app_name
import org.umamo.ui.resources.title_read_only
import org.umamo.ui.resources.title_untitled_document
import org.umamo.ui.theme.ProvideAppThemeFromSettings
import org.umamo.ui.theme.UmamoTheme
import org.umamo.ui.viewport.LiveParams
import java.awt.Desktop
import java.util.concurrent.atomic.AtomicReference
/**
* Applies the `UMAMO_DUMP_PARAMS` environment override (e.g. `ParamAngleX=30,ParamAngleY=-10`) to the
* given live params, so a deformed pose can be dumped headless. A desktop dev affordance - the shared
* initialLiveParams stays environment-free.
*
* @param LiveParams liveParams The initial document's parameter hand-off to rewrite.
*/
private fun applyDumpParamOverrides(liveParams: LiveParams) {
val spec = System.getenv("UMAMO_DUMP_PARAMS") ?: return
val values = liveParams.values.toMutableMap()
spec.split(",").forEach { pair ->
val parts = pair.split("=")
val value = parts.getOrNull(1)?.trim()?.toFloatOrNull()
if (parts.size == 2 && value != null) {
values[ParameterId(parts[0].trim())] = value
}
}
liveParams.values = values.toMap()
}
/**
* Loads the initial document from a `.cmo3`/`.moc3` path and applies the dump-param overrides.
*
* A function rather than inline code in [main] on purpose: main's frame lives for the whole run
* (application {} blocks), and an interpreted frame keeps every local reachable - a document held
* in one would stay pinned, retained CMO3 graph and decoded atlas included, long after another
* file replaces it. Loading in a popped frame leaves the holder in [main] as the only reference.
*
* @param String? initialPath The argv / -Dumamo.testCmo3 path, or null for none.
* @return Document? The loaded document, or null when there is no path or the load fails.
*/
private fun loadInitialDocument(initialPath: String?): Document? {
val path = initialPath ?: return null
// A failed initial load falls back to an empty shell (the failure is in the log); the in-app
// alert only covers interactive opens, since the shell is not up yet to show it here.
val document = (runBlocking { loadDocument(platformFileFromSavedPath(path)) } as? DocumentLoad.Loaded)?.document
// The dump-params override applies only to the initially-opened document - it exists for the
// headless first-frame dump, which always opens via argv / -Dumamo.testCmo3. PuppetDocument
// covers both CMO3 and MOC3 documents, so a .moc3 argv dump poses correctly too.
(document as? PuppetDocument)?.let { applyDumpParamOverrides(it.liveParams) }
return document
}
/**
* The window title: the app name, the open document's name, the unsaved marker, and the read-only marker.
*
* The name follows the `.uma` the document saves to once it has one, so a `Erica.cmo3` saved as `Erica.uma`
* reads as the latter. A document with no file is named here rather than by [Document.displayName], which
* is the plain-text name the log and an export's suggested file name need; the title is chrome, so it
* localizes. A read-only document says so, since Save is greyed for as long as it is open.
*
* @param Document? document The open document.
* @param String? savedPath The `.uma` the document saves to, or null before its first save.
* @param Boolean readOnly Whether the document opened read-only.
* @param Boolean dirty Whether the session has unsaved edits.
* @return String The title.
*/
@Composable
private fun windowTitleFor(document: Document?, savedPath: String?, readOnly: Boolean, dirty: Boolean): String {
val untitled = stringResource(Res.string.title_untitled_document)
val readOnlyMarker = stringResource(Res.string.title_read_only)
val name = savedPath?.let(::fileDisplayName) ?: document?.let { open -> if (open.path == null) untitled else open.displayName }
val markers = (if (dirty) " *" else "") + (if (readOnly) " $readOnlyMarker" else "")
return stringResource(Res.string.app_name) + (name?.let { " - $it$markers" }.orEmpty())
}
/**
* Whether [path] names a document the editor opens by itself - its own `.uma`, or a `.cmo3` / `.moc3` it imports.
* One test for the command line and the macOS open-file event, so a file the OS hands over is accepted the same
* way however it arrives. The extension only says the path is worth reading; the loader identifies the content.
*
* Artwork is deliberately not a document path: it is ADDED to whatever document is open, so a `.psd` argument
* would have nothing to be added to at this point in the launch.
*
* @param String path A path from the command line or the operating system.
* @return Boolean True when the path has a document extension.
*/
internal fun isOpenableDocumentPath(path: String): Boolean = FormatRegistry.kindForFileName(path)?.role == FileRole.Document
/**
* Desktop entrypoint. Opens a single editor window over the storage/settings foundation: window state
* (size/position) and the recent-files list restore from `:settings`, and File → Open/Save-As use the
* native `:storage` dialogs. An initial document may come from a `.uma`, `.cmo3`, or `.moc3` argument or
* `-Dumamo.testCmo3`; otherwise the window opens into a new, empty document.
* `UMAMO_DUMP_PNG` still dumps the first frame headlessly (the WSL verification path).
*
* Settings load synchronously here (the bundled default is a Compose resource, read via `runBlocking`)
* so the window state is ready before the window opens and the window is unconditional - `application {}`
* exits if it ever has zero windows, which an async settings gate would briefly cause.
*
* @param Array<String> args Optional: a `.uma`, `.cmo3`, or `.moc3` path.
*/
fun main(args: Array<String>) {
// FileKit's native dialogs need a one-time init; `appId` names the per-OS data/cache dirs it uses.
FileKit.init(appId = "umamo")
// Pick the first document argument; loadDocument then does the real magic-byte detection once the file
// is actually read (a .moc3 routes to the sidecar-discovering loader). This is how Windows and Linux hand
// over a double-clicked file.
val initialPath = args.firstOrNull(::isOpenableDocumentPath) ?: System.getProperty("umamo.testCmo3")
// macOS hands a double-clicked file over as an open-file event instead, at launch and for as long as the
// app runs. Installed before the window exists: a cold launch's event can arrive before the first
// composition, and the requests wait in their buffer until the shell collects them.
val openRequests = HostOpenRequests()
if (Desktop.isDesktopSupported() && Desktop.getDesktop().isSupported(Desktop.Action.APP_OPEN_FILE)) {
Desktop.getDesktop().setOpenFileHandler { event ->
event.files.map { file -> file.absolutePath }.firstOrNull(::isOpenableDocumentPath)?.let(openRequests::request)
}
}
// Synchronous load, like the settings below: the window opens with the document already in hand.
// The document reaches the first composition through a one-shot holder rather than a plain local:
// the application closure lives for the whole run, so a direct capture would keep the first
// document reachable after the user opens something else. remember empties the holder on first
// composition; only the path string stays behind for the recent-files record.
// A failed or absent argv load still opens a document - the new, empty one the editor starts in.
val initialDocumentHolder = AtomicReference(loadInitialDocument(initialPath) ?: newBlankDocument())
val initialDocumentPath = initialDocumentHolder.get()?.path
val storage = desktopAppStorage("umamo")
// A first run also seeds the system's language here, so the window - and the Quick Setup modal it opens
// with - is already in that language.
val settings = runBlocking { loadAppSettings(storage) }
// Apply the UI language before the window opens so the menu bar (which lives outside the shell's
// own locale scope) and every other stringResource resolve to the configured locale from the start.
applyAppLocale(settings.getString(LOCALE_SETTINGS_KEY) ?: FALLBACK_LOCALE_TAG)
UmamoLog.info("config=${storage.configDirectory}")
application {
var document by remember { mutableStateOf(initialDocumentHolder.getAndSet(null)) }
// The title's unsaved marker, mirrored from the session's dirty flag by the window content below,
// which is where the session lives.
var dirty by remember { mutableStateOf(false) }
// The title's file name and read-only marker, mirrored the same way from the document's save target,
// which is also derived inside the window content.
var savedPath by remember { mutableStateOf<String?>(null) }
var readOnly by remember { mutableStateOf(false) }
val windowState = remember { settings.savedWindowState() }
// A file opened from the command line is a real "open" - record it in recent files too.
LaunchedEffect(Unit) { initialDocumentPath?.let { settings.addRecentFile(it) } }
fun closeApp() {
settings.saveWindowState(windowState)
exitApplication()
}
// Every way out passes through the shell's unsaved-changes guard: the window's close button here, File >
// Exit inside the shell, and the macOS Quit below.
val exitGuard = rememberExitGuard()
// macOS routes Cmd+Q and the Dock's Quit through the application's quit handler, not the window's
// close request. Cancelling the OS's quit and asking the guard keeps one path; the handler is
// unsupported, and nothing is installed, on Windows and Linux.
DisposableEffect(exitGuard) {
val quitHandlerSupported = Desktop.isDesktopSupported() && Desktop.getDesktop().isSupported(Desktop.Action.APP_QUIT_HANDLER)
if (quitHandlerSupported) {
Desktop.getDesktop().setQuitHandler { _, response ->
response.cancelQuit()
exitGuard.request { closeApp() }
}
}
onDispose {
if (quitHandlerSupported) {
Desktop.getDesktop().setQuitHandler(null)
}
}
}
Window(
onCloseRequest = { exitGuard.request { closeApp() } },
state = windowState,
// Window + taskbar/dock icon. painterResource decodes the bundled app_icon PNG (the same
// mascot the packaged installer icons derive from); regenerate via docs/design/appicon/generate.sh.
icon = painterResource(Res.drawable.app_icon),
// A document that has never been saved has no file name to show, so the title localizes its own
// name for it rather than showing the plain-text one the log and export names use.
title = windowTitleFor(document, savedPath, readOnly, dirty),
) {
// The session is derived HERE, in the composition that reads the document, and not in the
// application scope above. Window content is its own composition: it reads the document
// state directly, but sees a value from the outer scope only through the content lambda it
// was last handed. A session derived outside reaches EditorApp one frame late, so a newly
// opened document composes once with the previous document's session - and the export
// command, the File menu, and the page resolver registered in that frame keep the stale
// pair. Deriving both in one place keeps them consistent in every frame.
val session = rememberEditorSessionFor(document)
val documentFile = rememberDocumentFileFor(document)
LaunchedEffect(documentFile) {
readOnly = documentFile?.readOnly == true
snapshotFlow { documentFile?.umaPath }.collect { path -> savedPath = path }
}
LaunchedEffect(session) {
val activeSession = session
if (activeSession == null) {
dirty = false
} else {
activeSession.dirty.collect { dirty = it }
}
}
CompositionLocalProvider(LocalSettings provides settings) {
ProvideAppThemeFromSettings {
// Run the whole window content inside UmamoTheme so LocalUmamoColors resolves to the active
// scheme for everything created here - the Windows title-bar tint AND the GL viewport host,
// which reads the themed grid-backdrop colors at creation (it lives outside the shell's
// own UmamoTheme). The shell re-applies the same theme to its subtree, an idempotent,
// cheap re-provide. Without this wrap LocalUmamoColors falls back to its static dark default,
// so the viewport grid never tracked the theme.
UmamoTheme {
WindowsTitleBarTint(window)
WindowResizeHeal(window)
EditorApp(
document = document,
session = session,
documentFile = documentFile,
onOpen = { document = it },
onExit = { closeApp() },
exitGuard = exitGuard,
viewportServiceFactory = { puppet, textures, liveParams ->
OffscreenPuppetService(puppet, textures, liveParams).also { it.start() }
},
openRequests = openRequests,
)
}
}
}
}
}
}
@@ -0,0 +1,110 @@
package org.umamo.editor.desktop
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.toArgb
import com.sun.jna.Library
import com.sun.jna.Native
import com.sun.jna.Pointer
import com.sun.jna.ptr.IntByReference
import org.umamo.ui.theme.LocalUmamoColors
import java.awt.Window
/*
* Desktop window-chrome integration: tint the host-OS title bar to match the editor's own palette so the
* caption does not sit as a bright system-colored strip above a dark app. Only Windows 11's Desktop Window
* Manager exposes this (DWMWA_CAPTION_COLOR); every other platform is a no-op. The caption color is read
* from [LocalUmamoColors] so it tracks the active light/dark theme.
*/
/**
* The DWM window attribute that sets the title-bar (caption) fill color.
*
* Win32: DWMWA_CAPTION_COLOR (dwmapi.h, value 35). Honored on Windows 11 build 22000 and later; older
* systems return a failure HRESULT, which we ignore so the call is harmless everywhere.
*/
private const val DWMWA_CAPTION_COLOR = 35
/**
* Minimal JNA binding to dwmapi.dll - only the single entry point we need. Loaded lazily and only on
* Windows (see [setWindowsCaptionColor]); the class is never touched on other platforms, so dwmapi.dll is
* never resolved there.
*/
private interface Dwmapi : Library {
/**
* Win32: DwmSetWindowAttribute. Sets a Desktop Window Manager attribute on a window.
*
* pvAttribute is passed by reference; for DWMWA_CAPTION_COLOR it points at a single COLORREF (DWORD),
* so [value] is an int-by-reference and [valueSize] is 4.
*
* @param Pointer windowHandle The target window's HWND.
* @param Int attribute The DWMWA_* attribute identifier.
* @param IntByReference value Pointer to the attribute value (a COLORREF here).
* @param Int valueSize Size of the value in bytes.
* @return Int The HRESULT; 0 (S_OK) on success.
* @note PascalCase is mandatory: JNA's interface mapper binds this method to the dwmapi.dll export of
* the same name, so it must match the Win32 symbol verbatim - hence the naming-rule suppression.
*/
@Suppress("ktlint:standard:function-naming")
fun DwmSetWindowAttribute(windowHandle: Pointer, attribute: Int, value: IntByReference, valueSize: Int): Int
}
/** The dwmapi.dll binding, resolved on first use. Only ever forced on Windows. */
private val dwmapi: Dwmapi by lazy { Native.load("dwmapi", Dwmapi::class.java) }
/**
* Converts a Compose [Color] to a Win32 COLORREF.
*
* Win32 COLORREF packs the channels as 0x00BBGGRR (blue high, red low, top byte zero) - the reverse of
* ARGB's byte order - so the red and blue channels are swapped relative to [toArgb].
*
* @return Int The COLORREF for this color.
*/
private fun Color.toColorRef(): Int {
val argb = toArgb()
val red = (argb shr 16) and 0xFF
val green = (argb shr 8) and 0xFF
val blue = argb and 0xFF
return (blue shl 16) or (green shl 8) or red
}
/**
* Sets the Windows title-bar caption color to [color] via the Desktop Window Manager. A no-op on any
* non-Windows OS, before the window has a native peer (no HWND yet), or on a Windows build that predates
* DWMWA_CAPTION_COLOR - in the last case DWM returns a failure HRESULT, which is deliberately ignored so
* the call degrades to "system default caption" rather than throwing.
*
* @param Window window The window whose caption to tint.
* @param Color color The desired caption fill color.
*/
private fun setWindowsCaptionColor(window: Window, color: Color) {
// Gate on the OS before touching the JNA binding, so dwmapi.dll is only ever loaded on Windows.
if (!System.getProperty("os.name").startsWith("Windows", ignoreCase = true)) {
return
}
if (!window.isDisplayable) {
return
}
val windowHandle = Native.getWindowPointer(window) ?: return
// HRESULT is ignored: a non-zero result (e.g. Windows 10, which lacks this attribute) just means the
// caption keeps its system color.
dwmapi.DwmSetWindowAttribute(windowHandle, DWMWA_CAPTION_COLOR, IntByReference(color.toColorRef()), Int.SIZE_BYTES)
}
/**
* Tints [window]'s host-OS title bar to the theme's window-background color (Windows 11 only; a no-op
* elsewhere). Reads [LocalUmamoColors], so place it under the app theme; it re-applies whenever the
* resolved background changes (a light/dark theme switch), keeping the caption in step with the UI.
*
* This composable emits no UI - it is purely a window-chrome side effect.
*
* @param Window window The host window whose caption to tint.
*/
@Composable
fun WindowsTitleBarTint(window: Window) {
val captionColor = LocalUmamoColors.current.windowBackground
LaunchedEffect(window, captionColor) {
setWindowsCaptionColor(window, captionColor)
}
}
@@ -0,0 +1,62 @@
package org.umamo.editor.desktop
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import java.awt.event.ComponentEvent
import javax.swing.JFrame
import javax.swing.Timer
/*
* On Windows, canceling an interactive resize with Escape restores the original window rect without
* a resize event: AWT silently syncs the frame's cached bounds (~750 ms later) but dispatches no
* componentResized and runs no layout. Compose derives its scene size, its layout, and
* WindowState.size from that missing event, so the content stays frozen at the dragged size inside
* the restored native window. This watchdog detects the desync and replays the pipeline the lost
* event would have driven.
*/
/** How often the heal watchdog compares the frame's bounds against its laid-out root pane. */
private const val HEAL_CHECK_INTERVAL_MILLIS = 250
/**
* Heals the window when the OS changes its bounds behind AWT's event stream (Escape-canceled
* resize). After every healthy resize the root pane is laid out to exactly the frame's bounds
* minus its insets, so a persistent mismatch is proof of a lost resize notification. On a
* mismatch this re-validates the component tree, which resizes the ComposeWindowPanel and with it
* the Compose scene, then dispatches a synthetic COMPONENT_RESIZED so Compose's own window
* listener refreshes WindowState.size. While bounds and layout agree - the permanent state on
* every platform outside this Windows quirk - each tick is two int comparisons on the EDT, so the
* watchdog runs unconditionally rather than behind an OS gate.
*
* This composable emits no UI - it only owns the watchdog timer's lifecycle.
*
* @param JFrame window The host window to watch and heal.
*/
@Composable
fun WindowResizeHeal(window: JFrame) {
DisposableEffect(window) {
val healTimer =
Timer(HEAL_CHECK_INTERVAL_MILLIS) {
if (!window.isShowing) {
return@Timer
}
val insets = window.insets
val expectedWidth = window.width - insets.left - insets.right
val expectedHeight = window.height - insets.top - insets.bottom
val rootPane = window.rootPane
if (expectedWidth > 0 &&
expectedHeight > 0 &&
(rootPane.width != expectedWidth || rootPane.height != expectedHeight)
) {
// Replay what a real resize event does: layout first so the scene and every Swing
// child match the true bounds, then the window-level event so Compose's listener
// re-reads the (already correct) width/height into WindowState.
window.invalidate()
window.validate()
window.dispatchEvent(ComponentEvent(window, ComponentEvent.COMPONENT_RESIZED))
}
}
healTimer.start()
onDispose { healTimer.stop() }
}
}
@@ -0,0 +1,59 @@
package org.umamo.editor.desktop
import androidx.compose.ui.unit.DpSize
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.WindowPlacement
import androidx.compose.ui.window.WindowPosition
import androidx.compose.ui.window.WindowState
import org.umamo.settings.Settings
/**
* The window size/position/placement to open with - restored from `interface.window.*`, or a sensible
* default (1280×800, platform-placed, floating) on first run. A window saved while maximized or fullscreen
* reopens that way; the persisted size/position are the floating restore geometry it returns to.
*
* @return WindowState The starting window state.
*/
fun Settings.savedWindowState(): WindowState {
val width = (getDouble("interface.window.width") ?: 1280.0).dp
val height = (getDouble("interface.window.height") ?: 800.0).dp
val x = getDouble("interface.window.x")
val y = getDouble("interface.window.y")
val position = if (x != null && y != null) WindowPosition(x.dp, y.dp) else WindowPosition.PlatformDefault
val placement =
when (getString("interface.window.placement")) {
"maximized" -> WindowPlacement.Maximized
"fullscreen" -> WindowPlacement.Fullscreen
else -> WindowPlacement.Floating
}
return WindowState(placement = placement, size = DpSize(width, height), position = position)
}
/**
* Persists [state]'s current placement, plus its size + position, to `interface.window.*` so the next launch
* restores them. Call on close (the [WindowState] tracks live resizes/moves/maximize, so it holds the final
* state). Size and position are recorded only while floating: when maximized or fullscreen, [state]'s size
* and position are the screen-filling bounds, so saving them would clobber the restore geometry the window
* should return to on un-maximize - the last floating geometry is kept instead.
*
* @param WindowState state The window state to persist.
*/
fun Settings.saveWindowState(state: WindowState) {
setString(
"interface.window.placement",
when (state.placement) {
WindowPlacement.Maximized -> "maximized"
WindowPlacement.Fullscreen -> "fullscreen"
WindowPlacement.Floating -> "floating"
},
)
if (state.placement == WindowPlacement.Floating) {
setDouble("interface.window.width", state.size.width.value.toDouble())
setDouble("interface.window.height", state.size.height.value.toDouble())
val position = state.position
if (position is WindowPosition.Absolute) {
setDouble("interface.window.x", position.x.value.toDouble())
setDouble("interface.window.y", position.y.value.toDouble())
}
}
}
@@ -0,0 +1,60 @@
package org.umamo.editor.desktop.viewport
import org.lwjgl.glfw.GLFW
import org.lwjgl.opengl.GL
import org.lwjgl.system.MemoryUtil
import org.umamo.render.gl.GlRenderDevice
/**
* The Windows / Linux offscreen GL context: a hidden GLFW window carrying a GL 3.3 core context, made
* current on the render thread.
*/
internal class GlfwOffscreenGlContext : OffscreenGlContext {
override val backendName: String = "GLFW"
private var window: Long = MemoryUtil.NULL
/**
* Creates the GLFW hidden-window GL 3.3 core context on this thread and makes it current. Returns false
* (degrading to a blank viewport) if GLFW init or window creation fails.
*
* @return Boolean True on success.
*/
override fun createAndMakeCurrent(): Boolean {
// On Linux Wayland sessions, LWJGL's GLFW often fails to create the hidden offscreen
// window, which leaves the puppet viewport blank. Prefer X11 (XWayland) when available.
val osName = System.getProperty("os.name").orEmpty().lowercase()
if (osName.contains("linux") && GLFW.glfwPlatformSupported(GLFW.GLFW_PLATFORM_X11)) {
GLFW.glfwInitHint(GLFW.GLFW_PLATFORM, GLFW.GLFW_PLATFORM_X11)
}
if (!GLFW.glfwInit()) {
return false
}
GLFW.glfwWindowHint(GLFW.GLFW_VISIBLE, GLFW.GLFW_FALSE)
GLFW.glfwWindowHint(GLFW.GLFW_CONTEXT_VERSION_MAJOR, 3)
GLFW.glfwWindowHint(GLFW.GLFW_CONTEXT_VERSION_MINOR, 3)
GLFW.glfwWindowHint(GLFW.GLFW_OPENGL_PROFILE, GLFW.GLFW_OPENGL_CORE_PROFILE)
GLFW.glfwWindowHint(GLFW.GLFW_OPENGL_FORWARD_COMPAT, GLFW.GLFW_TRUE)
window = GLFW.glfwCreateWindow(1, 1, "umamo-offscreen", MemoryUtil.NULL, MemoryUtil.NULL)
if (window == MemoryUtil.NULL) {
return false
}
GLFW.glfwMakeContextCurrent(window)
GL.createCapabilities()
return true
}
override fun describeContext(): String = GlRenderDevice().describeBackend()
/**
* Releases the GLFW window and unbinds the context. Runs on the render thread, where the context is
* current, after the engine's glFinish barrier.
*/
override fun destroy() {
if (window != MemoryUtil.NULL) {
GLFW.glfwMakeContextCurrent(MemoryUtil.NULL)
GLFW.glfwDestroyWindow(window)
window = MemoryUtil.NULL
}
}
}
@@ -0,0 +1,56 @@
package org.umamo.editor.desktop.viewport
import org.lwjgl.system.Configuration
/**
* An off-screen GL 3.3+ core context owned by a single render thread. The offscreen viewport renderer
* ([OffscreenRenderEngine]) renders only to framebuffer objects, so a context needs no visible window and no
* presentable drawable - just a current GL context on the thread that issues the draw and read-back calls.
*
* Threading contract: [createAndMakeCurrent], [describeContext], and [destroy] all run on the one render
* thread, in that order across the context's life; the context is never migrated to another thread.
*/
internal interface OffscreenGlContext {
/**
* A short backend label for the startup log line (for example "GLFW" or "CGL GL4_Core"), so the log
* records which path the running OS actually took.
*/
val backendName: String
/**
* Creates the context and makes it current on the calling (render) thread. On failure returns false so
* the caller degrades to a blank viewport rather than crashing - the same graceful fallback the engine
* already applies when GL is unavailable.
*
* @return Boolean True on success (a context is now current), false to degrade to a blank viewport.
*/
fun createAndMakeCurrent(): Boolean
/**
* The renderer / version / vendor / GLSL of the current context, for the startup diagnostic. Valid only
* after a successful [createAndMakeCurrent].
*
* @return String The context description.
*/
fun describeContext(): String
/**
* Releases the context on the render thread. Must NOT call glFinish - the engine issues one glFinish
* barrier before disposing its GL resources, and this runs last, after that barrier.
*/
fun destroy()
}
/**
* Selects the offscreen GL context implementation for the running OS. GLFW is used on all platforms.
*
* @return OffscreenGlContext The context backend for this OS.
*/
internal fun createOffscreenGlContext(): OffscreenGlContext {
val osName = System.getProperty("os.name").orEmpty().lowercase()
if (osName.contains("mac") || osName.contains("darwin")) {
// https://javadoc.lwjgl.org/org/lwjgl/glfw/package-summary.html#using-glfw-on-macos-heading
Configuration.GLFW_LIBRARY_NAME.set("glfw_async")
}
return GlfwOffscreenGlContext()
}
@@ -0,0 +1,217 @@
package org.umamo.editor.desktop.viewport
import androidx.compose.ui.graphics.ImageBitmap
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.withContext
import org.umamo.edit.GridConfig
import org.umamo.format.raster.RasterImage
import org.umamo.render.ContentBounds
import org.umamo.render.FrameBackdrop
import org.umamo.render.GridColors
import org.umamo.render.LayerDrawPlan
import org.umamo.render.LayerRasterBatch
import org.umamo.render.PuppetTextures
import org.umamo.render.ViewportCamera
import org.umamo.render.capturedOver
import org.umamo.render.pick.PickCandidate
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.PuppetModel
import org.umamo.ui.model.DrawableThumbnailProvider
import org.umamo.ui.viewport.AreaCameraKey
import org.umamo.ui.viewport.AtlasPageBinding
import org.umamo.ui.viewport.ImageFrame
import org.umamo.ui.viewport.LiveParams
import org.umamo.ui.viewport.PuppetViewportService
import org.umamo.ui.viewport.RenderedFrame
import org.umamo.ui.viewport.UvSceneContent
/**
* Renders the puppet OFF-SCREEN and publishes it as a Compose ImageBitmap per viewport area.
* Because the viewport is then lightweight Compose content, the UI layers over it correctly on every platform.
*
* This is the desktop implementation of [PuppetViewportService]. It is a thin facade that composes the
* pieces and forwards each call to the collaborator that owns it:
*
* - [ViewportAreaRegistry] - the registered areas + their cameras (register / resize / navigation), on the
* UI thread.
* - [OffscreenRenderEngine] - the render thread that owns the GL context, renderer, framebuffers, and
* async read-back, plus the render-input state (selection / shown / model / atlas pages / source
* artwork / grid / highlight colors).
* - [ViewportPicker] - CPU hit-testing and art thumbnails, on the UI thread (no GL).
*
* The GL context is chosen per OS behind [OffscreenGlContext], which is a hidden GLFW window on every
* desktop OS today (macOS only differs by loading the async GLFW library).
*
* Threading: every method here is called on the UI thread; the engine publishes frames from its render
* thread via the areas' StateFlows. Picking is CPU-side and synchronous.
*
* @property PuppetModel puppet The rig to render.
* @property PuppetTextures textures The atlas page(s).
* @property LiveParams liveParams The shared parameter hand-off (drives re-render on change).
*/
class OffscreenPuppetService(
puppet: PuppetModel,
textures: PuppetTextures,
liveParams: LiveParams,
) : PuppetViewportService {
private val registry = ViewportAreaRegistry()
private val engine = OffscreenRenderEngine(puppet, textures, liveParams, registry)
// The picker shares the engine's renderer for its pure-CPU pickGeometry()/drawnOrder() snapshots (the
// same instance the render thread draws with - those reads are CPU-only and UI-thread-safe).
private val picker = ViewportPicker(engine.puppetRenderer, textures, puppet)
/** Starts the render thread (call once, after construction). */
fun start() {
engine.start()
}
override var zoomStepPercent: Float
get() = registry.zoomStepPercent
set(value) {
registry.zoomStepPercent = value
}
override var zoomStepCoarsePercent: Float
get() = registry.zoomStepCoarsePercent
set(value) {
registry.zoomStepCoarsePercent = value
}
override var supersampleEnabled: Boolean
get() = engine.supersampleEnabled
set(value) {
engine.supersampleEnabled = value
}
override var supersampleWhileResizing: Boolean
get() = engine.supersampleWhileResizing
set(value) {
engine.supersampleWhileResizing = value
}
override var gridColors: GridColors
get() = engine.gridColors
set(value) {
engine.gridColors = value
}
override var gridConfig: GridConfig
get() = engine.gridConfig
set(value) {
engine.gridConfig = value
}
override fun register(areaId: String): StateFlow<RenderedFrame?> = registry.register(areaId)
override fun registerUvScene(areaId: String, content: UvSceneContent, islandExtent: ContentBounds?): StateFlow<RenderedFrame?> =
registry.registerUvScene(areaId, content, islandExtent)
override fun setUvSceneContent(areaId: String, content: UvSceneContent, islandExtent: ContentBounds?) =
registry.setUvSceneContent(areaId, content, islandExtent)
override fun unregister(areaId: String) = registry.unregister(areaId)
override fun cameraFlow(areaId: String): StateFlow<ViewportCamera?> = registry.cameraFlow(areaId)
override fun cameras(): Map<AreaCameraKey, ViewportCamera> = registry.cameras()
override fun seedCameras(cameras: Map<AreaCameraKey, ViewportCamera>) = registry.seedCameras(cameras)
override fun resize(areaId: String, width: Int, height: Int) = registry.resize(areaId, width, height)
override fun pan(areaId: String, deltaXpx: Float, deltaYpx: Float) = registry.pan(areaId, deltaXpx, deltaYpx)
override fun zoomAtCursor(areaId: String, zoomIn: Boolean, coarse: Boolean, cursorXpx: Float, cursorYpx: Float) =
registry.zoomAtCursor(areaId, zoomIn, coarse, cursorXpx, cursorYpx)
override fun zoomCentered(areaId: String, zoomIn: Boolean, coarse: Boolean) =
registry.zoomCentered(areaId, zoomIn, coarse)
override fun zoomToRegion(areaId: String, leftPx: Float, topPx: Float, rightPx: Float, bottomPx: Float) =
registry.zoomToRegion(areaId, leftPx, topPx, rightPx, bottomPx)
override fun actualSize(areaId: String) = registry.actualSize(areaId)
override fun fit(areaId: String) = registry.fit(areaId)
override fun fitWorldRect(areaId: String, minX: Float, minZ: Float, maxX: Float, maxZ: Float) =
registry.fitWorldRect(areaId, minX, minZ, maxX, maxZ)
override fun setSelection(ids: Set<DrawableId>) = engine.setSelection(ids)
override fun setActiveSelection(id: DrawableId?) = engine.setActiveSelection(id)
override fun setShownDrawables(ids: Set<DrawableId>) = engine.setShownDrawables(ids)
override fun setEditMeshFrozen(ids: Set<DrawableId>) = engine.setEditMeshFrozen(ids)
override fun setSourceLayerPlan(plan: LayerDrawPlan) = engine.setSourceLayerPlan(plan)
override fun setAtlasPages(binding: AtlasPageBinding) {
engine.setAtlasPages(binding)
// The picker samples page alpha CPU-side, so its pixels must move with the GPU's - a stale set
// would reject clicks on visible art at the re-derived coordinates.
picker.setTextures(binding.textures)
}
override fun deliverSourceLayerRasters(batch: LayerRasterBatch) = engine.deliverSourceLayerRasters(batch)
/**
* Pushes the latest model to the render engine and, when it actually changed, rebuilds the picker's
* model-derived lookup maps so session-created drawables stay pickable / sampleable / labeled.
*
* @param PuppetModel model The current model.
*/
override fun setModel(model: PuppetModel) {
if (engine.setModel(model)) {
picker.updateModel(model)
}
}
override fun setSelectionHighlightColor(red: Float, green: Float, blue: Float) =
engine.setSelectionHighlightColor(red, green, blue)
override fun setActiveSelectionHighlightColor(red: Float, green: Float, blue: Float) =
engine.setActiveSelectionHighlightColor(red, green, blue)
override fun pickAt(areaId: String, cursorXpx: Float, cursorYpx: Float): DrawableId? {
val view = registry.viewFor(areaId) ?: return null
return picker.pickAt(view.camera, view.width, view.height, cursorXpx, cursorYpx)
}
override fun pickAllAt(areaId: String, cursorXpx: Float, cursorYpx: Float): List<PickCandidate> {
val view = registry.viewFor(areaId) ?: return emptyList()
return picker.pickAllAt(view.camera, view.width, view.height, cursorXpx, cursorYpx)
}
override fun drawableWorldCentroids(): Map<DrawableId, FloatArray> = picker.drawableWorldCentroids()
/**
* Queues the capture on the render thread and, once its pixels arrive, converts them off the UI thread
* from the framebuffer's premultiplied color to the straight alpha an image file stores.
*
* @param ImageFrame frame The camera and pixel size to render.
* @param FrameBackdrop backdrop What the puppet is drawn over.
* @return RasterImage? The image, straight alpha, or null when the render thread could not serve it.
*/
override suspend fun renderImage(frame: ImageFrame, backdrop: FrameBackdrop): RasterImage? {
val premultiplied = engine.requestSnapshot(frame.camera, frame.width, frame.height, backdrop).await() ?: return null
return withContext(Dispatchers.Default) { premultiplied.capturedOver(backdrop) }
}
override fun areaView(areaId: String): ImageFrame? = registry.viewFor(areaId)?.let { view -> ImageFrame(view.camera, view.width, view.height) }
override fun visibleContentBounds(): ContentBounds? = engine.puppetRenderer.posedContentBounds(engine.shownDrawables)
override fun thumbnailFor(id: DrawableId): ImageBitmap? = picker.thumbnailFor(id)
override fun thumbnails(): DrawableThumbnailProvider = picker.thumbnails()
override fun partNameFor(id: DrawableId): String? = picker.partNameFor(id)
override fun drawableNameFor(id: DrawableId): String? = picker.drawableNameFor(id)
override fun dispose() = engine.dispose()
}
@@ -0,0 +1,976 @@
package org.umamo.editor.desktop.viewport
import kotlinx.coroutines.CompletableDeferred
import kotlinx.coroutines.Deferred
import org.lwjgl.opengl.GL11
import org.umamo.edit.GridConfig
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import org.umamo.render.ContentBounds
import org.umamo.render.DecodedImage
import org.umamo.render.FrameBackdrop
import org.umamo.render.GridColors
import org.umamo.render.LayerDrawPlan
import org.umamo.render.LayerRasterBatch
import org.umamo.render.PuppetTextures
import org.umamo.render.SupersampledSurface
import org.umamo.render.ViewportCamera
import org.umamo.render.device.ReadbackTicket
import org.umamo.render.gl.GlRenderDevice
import org.umamo.render.puppet.PuppetRenderer
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.KeyableTarget
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.visibleDrawableIds
import org.umamo.storage.UmamoLog
import org.umamo.ui.graphics.RgbaAlphaType
import org.umamo.ui.graphics.rgbaToImageBitmap
import org.umamo.ui.viewport.AtlasPageBinding
import org.umamo.ui.viewport.LiveParams
import org.umamo.ui.viewport.RenderedFrame
import org.umamo.ui.viewport.UvSceneContent
import java.io.File
import java.util.ArrayDeque
import java.util.concurrent.ConcurrentLinkedQueue
/**
* Framebuffer pixels per display pixel while supersampling is on: the whole pipeline renders 2x and
* box-downscales on resolve. Supersampling off collapses the scale to 1.
*/
internal const val RENDER_SUPERSAMPLE = 2
/** Idle poll when nothing changed and no read-back is in flight (about 60 Hz wake to pick up new params). */
private const val IDLE_MILLIS = 16L
/** Short poll while a read-back is in flight, so its result is collected with low latency. */
private const val BUSY_MILLIS = 1L
/**
* Minimum interval between resize-driven re-renders while an area's size is actively changing (a
* gutter drag or a window-edge resize): about 10 Hz of live feedback, with the Compose side
* stretching the previous frame between them. Pose / camera / state changes are never throttled.
*/
private const val RESIZE_THROTTLE_NANOS = 50_000_000L
/** How long a size must hold still before it counts as settled (the full-quality render then runs). */
private const val RESIZE_SETTLE_NANOS = 25_000_000L
/**
* The render engine: a dedicated daemon thread owns the GL context, the [PuppetRenderer], the supersample
* framebuffers, and the async read-back pool, and runs the render loop. It holds the render-input state the
* UI thread pushes (selection, shown set, model, atlas pages, source artwork, grid, highlight colors), renders
* each registered area whose pose / size / camera / backdrop changed, and publishes finished frames to the
* area's slot.
*
* The read-back is asynchronous (PBO + fence) so the thread never blocks on the GPU while a slider drags.
* Every 2D area of one document shows the same puppet at the same pose (the shared [liveParams]), so those
* areas differ only by size and camera; re-renders happen only when the pose or an area's
* size / camera / scene content / backdrop changes.
*
* @property PuppetModel puppet The rig to render.
* @property PuppetTextures textures The atlas page(s).
* @property LiveParams liveParams The shared parameter hand-off (drives re-render on change).
* @property ViewportAreaRegistry registry The area slots this engine renders and fits.
*/
internal class OffscreenRenderEngine(
private val puppet: PuppetModel,
private val textures: PuppetTextures,
private val liveParams: LiveParams,
private val registry: ViewportAreaRegistry,
) {
// The GL backend the renderer draws through; render-thread-owned, like every GL object here.
private val device = GlRenderDevice()
// GL handles + async read-back state, all owned by the render thread.
private val renderer =
PuppetRenderer(puppet, textures, device).apply {
// The editor viewport shows the world-origin axes (red X / blue Z behind the puppet); the
// renderer default is off so headless render-diff tests stay line-free.
setWorldAxesVisible(true)
}
/** The shared renderer, exposed so the facade can build the CPU picker over its pickGeometry()/drawnOrder(). */
val puppetRenderer: PuppetRenderer
get() = renderer
private val context = createOffscreenGlContext()
// The supersampled draw + display-size resolve target pair, device-owned and backend-neutral.
private val surface = SupersampledSurface(device, RENDER_SUPERSAMPLE)
/** An asynchronous read-back in flight: the device ticket plus what the pixels will mean on arrival. */
private class PendingFrame(
val ticket: ReadbackTicket,
val areaId: String,
val camera: ViewportCamera,
val model: PuppetModel,
)
// In-flight read-backs in submission order; polled front-first each loop tick. Render-thread only.
private val pendingFrames = ArrayDeque<PendingFrame>()
/**
* An image capture waiting for the render thread: what to draw, and where its pixels go.
*
* @property ViewportCamera camera The capture's camera.
* @property Int width The image width in pixels.
* @property Int height The image height in pixels.
* @property FrameBackdrop backdrop What the puppet is drawn over.
* @property CompletableDeferred<RasterImage?> result Completed with the premultiplied pixels, or null.
*/
private class PendingSnapshot(
val camera: ViewportCamera,
val width: Int,
val height: Int,
val backdrop: FrameBackdrop,
val result: CompletableDeferred<RasterImage?>,
)
// Captures queued by the UI thread and taken up by the render thread between frames. A queue for the same
// reason as the raster batches: two requests landing in one tick must both be served.
private val pendingSnapshots = ConcurrentLinkedQueue<PendingSnapshot>()
// False once the render thread can no longer serve a capture (its context never came up, or it has shut
// down), so a request made after that is answered at once instead of waiting forever.
@Volatile
private var acceptingSnapshots = true
@Volatile
private var running = true
// Daemon so it can never block JVM exit; clean teardown still happens via dispose() -> join.
private val renderThread = Thread({ renderLoop() }, "umamo-offscreen-gl").apply { isDaemon = true }
// --- Render inputs: written by the UI thread (volatile publishes of immutable values / scalars), read by
// the render thread each frame. A change bumps a render-version counter the loop folds into per-area
// freshness, so a state-only change (no resize / pose / camera change) still forces exactly one redraw.
// The grid backdrop colors, fed from the editor theme; default to the neutral grey grid until the host
// pushes the themed colors.
@Volatile
private var gridColorsBacking: GridColors = GridColors.Classic
// The per-document grid geometry (major spacing + subdivisions), fed from the session.
@Volatile
private var gridConfigBacking: GridConfig = GridConfig()
// The currently selected drawables, read by the render thread to tint them.
@Volatile
private var selectionBacking: Set<DrawableId> = emptySet()
// The active (last-selected) drawable, tinted apart from the rest of a multi-selection; null when none.
@Volatile
private var activeSelectionBacking: DrawableId? = null
// The drawables actually drawn (the resolved Parts-panel visibility cascade). Seeded from the open
// model's static cascade.
@Volatile
private var shownBacking: Set<DrawableId> = puppet.visibleDrawableIds()
// Edit-session drawable ids whose textured GPU mesh is frozen as the mesh-edit guide image. Empty
// outside Edit mode. Applied on the render thread before updateModel so topology edits keep the image.
@Volatile
private var editMeshFrozenBacking: Set<DrawableId> = emptySet()
// Which artwork the puppet's drawables map onto, published whole. EMPTY is the atlas, which is where
// every document starts until a plan is prepared for it. The pixels are NOT here: they arrive
// through the queue below, in answer to what the renderer asks for.
@Volatile
private var layerPlanBacking: LayerDrawPlan = LayerDrawPlan.EMPTY
// Decoded artwork waiting to be uploaded, drained on the render thread. A queue rather than a
// volatile slot because deliveries are chunked - two batches landing between frames must both be
// taken up, where a slot would silently drop the first.
private val pendingRasterBatches = ConcurrentLinkedQueue<LayerRasterBatch>()
// The latest model, re-pushed on a structural edit (layer reorder / reparent, base-mesh move); seeded
// with the open model.
@Volatile
private var modelBacking: PuppetModel = puppet
// The construction-time page pair: the pages initGl uploads, tagged with the atlas they render.
// Seeds both the published slot and the applied state, so the loop's first tick applies nothing
// unless a binding was pushed before the thread started.
private val initialAtlasBinding = AtlasPageBinding(puppet.atlas, textures)
// The latest page set, published whole with the atlas value it was composed for. The loop applies
// it and an atlas-changing model as one pair - see the pairing note in renderLoop.
@Volatile
private var atlasBindingBacking: AtlasPageBinding = initialAtlasBinding
// The pair the render thread has actually applied. Render-thread-owned after start(); read by the
// UV fit path (pageContentBounds), which also runs on the render thread.
private var appliedAtlasBinding: AtlasPageBinding = initialAtlasBinding
@Volatile
private var puppetRenderBump: Long = 0
// The UV editor's flat scenes (atlas page, source layer) bump separately from the puppet, so a puppet
// update does not needlessly re-render them.
@Volatile
private var atlasRenderBump: Long = 0
// The color selected drawables are tinted toward; RGB, each 0..1, defaults to the classic blue accent.
@Volatile
private var highlightRed: Float = 0.20f
@Volatile
private var highlightGreen: Float = 0.55f
@Volatile
private var highlightBlue: Float = 1.0f
// The color the active drawable is tinted toward; RGB, each 0..1, defaults to the edit-mode active green.
@Volatile
private var activeHighlightRed: Float = 0.49f
@Volatile
private var activeHighlightGreen: Float = 0.89f
@Volatile
private var activeHighlightBlue: Float = 0.0f
// The performance settings (viewport.rendering.*): whether settled frames supersample at all, and
// whether frames rendered while a size is actively changing keep the supersample (false = drop to
// 1x for a quarter of the fill cost during gutter drags and window resizes).
@Volatile
private var supersampleBacking: Boolean = true
@Volatile
private var supersampleWhileResizingBacking: Boolean = true
private var dumped = false
/** Starts the render thread (call once). */
fun start() {
renderThread.start()
}
/** Stops the render thread and releases the GL context. Blocks briefly to join. */
fun dispose() {
running = false
renderThread.join(2000)
acceptingSnapshots = false
failPendingSnapshots()
}
/**
* The drawables actually drawn (the resolved visibility cascade), as last pushed - what a capture's
* framing measures.
*/
val shownDrawables: Set<DrawableId>
get() = shownBacking
/**
* Queues an image capture of the current pose for the render thread, which takes it up between frames
* with the latest model, pages, artwork, shown set, and pose applied.
*
* Always completes: with the premultiplied pixels, or with null when the render thread cannot serve it.
* The check comes after the enqueue, so a shutdown racing the request still sweeps it up.
*
* @param ViewportCamera camera The capture's camera.
* @param Int width The image width in pixels.
* @param Int height The image height in pixels.
* @param FrameBackdrop backdrop What the puppet is drawn over.
* @return Deferred<RasterImage?> The premultiplied pixels, top row first, or null.
*/
fun requestSnapshot(camera: ViewportCamera, width: Int, height: Int, backdrop: FrameBackdrop): Deferred<RasterImage?> {
val snapshot = PendingSnapshot(camera, width, height, backdrop, CompletableDeferred())
pendingSnapshots.add(snapshot)
if (!acceptingSnapshots) {
failPendingSnapshots()
}
return snapshot.result
}
/** Answers every queued capture with null: the render thread will not serve them. */
private fun failPendingSnapshots() {
while (true) {
val snapshot = pendingSnapshots.poll() ?: break
snapshot.result.complete(null)
}
}
/**
* Renders every queued capture, on the render thread. A capture that fails logs and completes null; it
* never takes the render loop down with it.
*
* A shutdown stops the work at the next tile, so dispose() waits for one tile rather than a whole large
* image; what is left in the queue is answered by the loop's teardown.
*/
private fun serveSnapshots() {
while (running) {
val snapshot = pendingSnapshots.poll() ?: break
try {
if (snapshot.backdrop == FrameBackdrop.Grid) {
// The area renders apply the grid per render; a capture over it applies its own the same way.
val gridConfigApplied = gridConfigBacking
renderer.setGrid(gridColorsBacking, gridConfigApplied.scale, gridConfigApplied.subdivisions)
}
val image = renderer.renderSnapshot(snapshot.camera, snapshot.width, snapshot.height, snapshot.backdrop) { running }
if (image == null) {
UmamoLog.info("[GL] image capture (${snapshot.width}x${snapshot.height}) abandoned at shutdown")
}
snapshot.result.complete(image)
} catch (failure: Exception) {
UmamoLog.error("[GL] image capture (${snapshot.width}x${snapshot.height}) failed", failure)
snapshot.result.complete(null)
} catch (failure: OutOfMemoryError) {
// The stitched image is the one large allocation here, and running short of it costs this
// capture, not the viewport.
UmamoLog.error("[GL] image capture (${snapshot.width}x${snapshot.height}) ran out of memory", failure)
snapshot.result.complete(null)
}
}
}
/**
* The grid backdrop colors (background / major / minor). A change bumps both render passes so a
* color-only change repaints without waiting for an unrelated render.
*/
var gridColors: GridColors
get() = gridColorsBacking
set(value) {
if (value != gridColorsBacking) {
gridColorsBacking = value
doPuppetRenderBump()
doAtlasRenderBump()
}
}
/**
* The per-document grid geometry (major spacing + subdivisions). Like the grid colors, a change bumps
* both render passes so a grid-only change repaints without waiting for an unrelated render.
*/
var gridConfig: GridConfig
get() = gridConfigBacking
set(value) {
if (value != gridConfigBacking) {
gridConfigBacking = value
doPuppetRenderBump()
doAtlasRenderBump()
}
}
/**
* Sets the highlighted drawables (object-mode selection). A change bumps the puppet render version so the
* loop re-renders every area once with the new tint; an identical set is a no-op.
*
* @param Set<DrawableId> ids The selected drawable ids.
*/
fun setSelection(ids: Set<DrawableId>) {
if (ids != selectionBacking) {
selectionBacking = ids
doPuppetRenderBump()
}
}
/**
* Sets the active (last-selected) drawable, tinted apart from the rest of a multi-selection. A change
* bumps the puppet render version; an identical value is a no-op.
*
* @param DrawableId id The active drawable id, or null when none is active.
*/
fun setActiveSelection(id: DrawableId?) {
if (id != activeSelectionBacking) {
activeSelectionBacking = id
doPuppetRenderBump()
}
}
/**
* Sets which drawables are drawn (the resolved Parts-panel visibility cascade). A change bumps the puppet
* render version so every area re-renders once; the geometry is unchanged, so only the draw filter moves.
*
* @param Set<DrawableId> ids The drawable ids to draw.
*/
fun setShownDrawables(ids: Set<DrawableId>) {
if (ids != shownBacking) {
shownBacking = ids
doPuppetRenderBump()
}
}
/**
* Freezes Edit-session textured meshes as the mesh-edit guide image (see
* [PuppetRenderer.setEditMeshFrozen]). A change bumps the puppet render version.
*
* @param Set<DrawableId> ids The Edit-session drawable ids to freeze, or empty to thaw.
*/
fun setEditMeshFrozen(ids: Set<DrawableId>) {
if (ids != editMeshFrozenBacking) {
editMeshFrozenBacking = ids
doPuppetRenderBump()
}
}
/**
* Sets which artwork the puppet's drawables map onto; an empty plan displays from the atlas.
*
* A volatile publish of one immutable value, like every other render input. The render loop hands
* it to the renderer, which is where the GPU work happens - this must not touch the device.
*
* @param LayerDrawPlan plan Each drawable's mapping into the document's artwork.
*/
fun setSourceLayerPlan(plan: LayerDrawPlan) {
if (plan !== layerPlanBacking) {
layerPlanBacking = plan
doPuppetRenderBump()
}
}
/**
* Queues decoded artwork for upload on the render thread.
*
* @param LayerRasterBatch batch The decoded artwork.
*/
fun deliverSourceLayerRasters(batch: LayerRasterBatch) {
pendingRasterBatches.add(batch)
doPuppetRenderBump()
}
/**
* Publishes the atlas page set the current model's placements render from. A pure volatile
* publish: the render loop bumps its own freshness when it APPLIES the binding, because applying
* can lag the publish by a tick while the matching model arrives - a bump here would let an area
* render back to freshness against the outgoing pair and never take the new one up.
*
* @param AtlasPageBinding binding The pages plus the atlas value they belong to.
*/
fun setAtlasPages(binding: AtlasPageBinding) {
if (binding !== atlasBindingBacking) {
atlasBindingBacking = binding
}
}
/**
* Pushes the latest model so the render thread can reconcile it after an edit (a layer reorder
* re-derives the render order; a base-mesh move re-uploads the changed drawables' VBOs). A new (different)
* instance bumps the puppet render version so every area re-renders once.
*
* @param PuppetModel model The current model.
* @return Boolean True when the model actually changed (so the caller rebuilds model-derived state).
*/
fun setModel(model: PuppetModel): Boolean {
if (model !== modelBacking) {
modelBacking = model
doPuppetRenderBump()
return true
}
return false
}
/**
* Sets the color selected drawables are tinted toward (the selection highlight). A change bumps the
* puppet render version; an identical color is a no-op.
*
* @param Float red The tint red, 0..1.
* @param Float green The tint green, 0..1.
* @param Float blue The tint blue, 0..1.
*/
fun setSelectionHighlightColor(red: Float, green: Float, blue: Float) {
if (red != highlightRed || green != highlightGreen || blue != highlightBlue) {
highlightRed = red
highlightGreen = green
highlightBlue = blue
doPuppetRenderBump()
}
}
/**
* Sets the color the active drawable is tinted toward (the active-selection highlight). A change bumps the
* puppet render version; an identical color is a no-op.
*
* @param Float red The tint red, 0..1.
* @param Float green The tint green, 0..1.
* @param Float blue The tint blue, 0..1.
*/
fun setActiveSelectionHighlightColor(red: Float, green: Float, blue: Float) {
if (red != activeHighlightRed || green != activeHighlightGreen || blue != activeHighlightBlue) {
activeHighlightRed = red
activeHighlightGreen = green
activeHighlightBlue = blue
doPuppetRenderBump()
}
}
/**
* Whether settled frames render supersampled at all (viewport.rendering.supersample). Off renders
* everything at 1x - the whole-session performance escape hatch for weak GPUs. A change bumps
* both render passes so every area repaints at the new quality.
*/
var supersampleEnabled: Boolean
get() = supersampleBacking
set(value) {
if (value != supersampleBacking) {
supersampleBacking = value
doPuppetRenderBump()
doAtlasRenderBump()
}
}
/**
* Whether frames rendered while an area's size is actively changing keep the supersample
* (viewport.rendering.supersampleWhileResizing). False (the default) drops those frames to 1x;
* the settle render restores full quality within the settle window. No bump on change - the next
* resize simply picks up the new policy.
*/
var supersampleWhileResizing: Boolean
get() = supersampleWhileResizingBacking
set(value) {
supersampleWhileResizingBacking = value
}
/**
* Bump the render version for puppets to increase the frame by one.
*/
fun doPuppetRenderBump() {
puppetRenderBump++
}
/**
* Bump the render version for atlases to increase the frame by one.
*/
fun doAtlasRenderBump() {
atlasRenderBump++
}
/**
* The render thread body: create the context, then loop - collect finished read-backs, issue new renders
* for changed areas, and idle when there is nothing to do.
*/
private fun renderLoop() {
if (!context.createAndMakeCurrent()) {
UmamoLog.warn("[GL] offscreen context unavailable (${context.backendName}); viewport will stay blank")
acceptingSnapshots = false
failPendingSnapshots()
return
}
UmamoLog.info("[GL] offscreen via ${context.backendName}: ${context.describeContext()}")
try {
renderer.initGl()
var lastParams: Map<ParameterId, Float>? = null
var lastOverrides: Map<KeyableTarget, ChannelValue>? = null
var lastShown: Set<DrawableId>? = null
var lastModel: PuppetModel? = null
var lastLayerPlan: LayerDrawPlan? = null
var paramsVersion = 0L
while (running) {
collectCompleted()
val params = liveParams.values
val shown = shownBacking
// Pages and model apply as a consistent PAIR - the decision itself is pure and tested
// (resolveAtlasPairing); this block only carries it out.
val pairing = resolveAtlasPairing(modelBacking, atlasBindingBacking, appliedAtlasBinding, lastModel)
val orderModel = pairing.orderModel
pairing.applyBinding?.let { binding ->
// Pages first, then the model that samples them. The freshness bumps happen HERE, at
// apply, not at publish: paramsVersion re-renders the puppet areas, the atlas bump the
// UV page areas (whose AtlasPage content compares by index and cannot see same-index-
// new-pixels). A concurrent UI-thread bump can collapse into this one; both causes are
// covered by the single re-render that follows either way.
renderer.setAtlasPages(binding.textures)
appliedAtlasBinding = binding
paramsVersion++
doAtlasRenderBump()
}
// The artwork hand-off, on the render thread where the uploads belong. The mapping is
// compared by identity: it is published whole, so a new reference IS the change.
val layerPlan = layerPlanBacking
if (layerPlan !== lastLayerPlan) {
renderer.setSourceLayerPlan(layerPlan)
lastLayerPlan = layerPlan
}
// Then any decoded pixels that arrived since the last frame. Drained rather than sampled:
// the producer chunks its deliveries so visible art lands first, and skipping a batch would
// strand whatever it carried on the atlas until the working set happened to move again.
while (true) {
val batch = pendingRasterBatches.poll() ?: break
renderer.deliverSourceLayerRasters(batch)
}
// Edit-mode guide freeze must land before updateModel so a topology delete in the same tick
// keeps the textured mesh. Applied every tick (cheap set-equality no-op when unchanged).
renderer.setEditMeshFrozen(editMeshFrozenBacking)
// Rebuild the pose - and thus the draw list, which setPose filters by the shown set and sorts by
// the render order - when the pose, the visibility cascade, OR the render order changes. A
// visibility toggle or a layer reorder leaves the params untouched, so without these checks the
// draw list would never refresh. setShownDrawables / updateModel run first so setPose uses them.
// The override map is compared by identity like the params map: both are swapped wholesale on
// the UI thread, so a reference change is exactly "something moved".
val overrides = liveParams.channelOverrides
if (params !== lastParams || overrides !== lastOverrides || shown !== lastShown || orderModel !== lastModel) {
renderer.setShownDrawables(shown)
if (orderModel !== lastModel) {
// Re-point the renderer at the edited model so the next setPose re-derives the draw order
// and (for a deformer reparent) the deform chain.
renderer.updateModel(orderModel)
lastModel = orderModel
}
renderer.setPose(params, overrides)
lastParams = params
lastOverrides = overrides
lastShown = shown
paramsVersion++
}
// Captures run after the hand-offs above, so each one shows exactly the state the areas are about
// to render. A capture leaves the renderer's camera, scale, and selection as it found them, and
// every area render sets its own anyway.
serveSnapshots()
var pendingWork = pendingFrames.isNotEmpty()
val nowNanos = System.nanoTime()
val settleScale = if (supersampleBacking) RENDER_SUPERSAMPLE else 1
// With supersampling off both scales collapse to 1, so supersampleWhileResizing is
// inert by construction (the preferences UI disables its checkbox to say so).
val interactiveScale = if (supersampleWhileResizingBacking) settleScale else 1
for ((areaId, slot) in registry.areas) {
val width = slot.width
val height = slot.height
if (width <= 0 || height <= 0) {
continue
}
// Track size-change recency for the resize throttle. The FIRST observation (a fresh
// slot, observed 0x0) does not stamp, so a newly opened area counts as settled and its
// first frame renders at full quality immediately.
if (width != slot.observedWidth || height != slot.observedHeight) {
val firstObservation = slot.observedWidth == 0 && slot.observedHeight == 0
slot.observedWidth = width
slot.observedHeight = height
if (!firstObservation) {
slot.sizeChangedNanos = nowNanos
}
}
if (slot.inFlight) {
pendingWork = true
continue // one read-back per area in flight; coalesces a flurry of slider moves
}
// Establish or refit the camera now that the size is known - the render thread owns the
// content bounds; the registry restores a remembered camera or fits fresh, and swaps a UV
// area's view when the page or layer it shows has changed.
val camera = registry.establishCamera(slot, areaId, width, height) { scene, content -> contentBoundsFor(scene, content) }
// Freshness splits into the size axis (throttled during an active resize) and the rest.
// A frame rendered below the settle scale stays size-stale on purpose, so the settle
// pass re-renders it at full quality once the size holds still.
// A UV scene is model-independent, so its freshness ignores the pose version and
// puppetRenderBump: it re-renders only on size / camera / the surface it shows (the page index
// or the layer raster), plus the grid colors and geometry it draws its backdrop with - tracked
// by atlasRenderBump. The puppet keeps the full freshness via puppetRenderBump.
val sizeFresh = slot.renderedWidth == width && slot.renderedHeight == height && slot.renderedScale == settleScale
val restFresh =
when (slot.scene) {
RenderScene.Puppet2D ->
slot.renderedParamsVersion == paramsVersion &&
slot.renderedCamera === camera &&
slot.puppetRenderBumpDone == puppetRenderBump
// Kind and payload are read as ONE value, so a switch can never be observed half
// applied. Equality rather than identity: AtlasPage compares its index, and
// SourceLayer's image compares by reference, which is the freshness test either
// surface wants.
RenderScene.UvScene ->
slot.renderedUvContent == slot.uvContent &&
slot.renderedCamera === camera &&
slot.atlasRenderBumpDone == atlasRenderBump
}
if (sizeFresh && restFresh) {
continue
}
if (restFresh && shouldDeferResizeRender(slot, nowNanos)) {
// Deliberately NOT pendingWork: with no read-back in flight the loop then sleeps
// IDLE_MILLIS (16 ms) and revisits, which cannot oversleep the RESIZE_SETTLE_NANOS or the
// RESIZE_THROTTLE_NANOS window - flagging pendingWork with an empty pendingFrames queue
// would skip both sleeps and busy-spin instead.
continue
}
// A size still in motion renders at the interactive scale; pose / camera / state changes
// during that motion share the burst's quality rather than forcing a full-scale render.
val sizeInMotion = nowNanos - slot.sizeChangedNanos < RESIZE_SETTLE_NANOS
val renderScale = if (sizeInMotion) interactiveScale else settleScale
if (width != slot.renderedWidth || height != slot.renderedHeight) {
slot.resizeRenderNanos = nowNanos
}
issueRender(areaId, slot, width, height, paramsVersion, camera, orderModel, renderScale)
pendingWork = true
}
if (!pendingWork) {
Thread.sleep(IDLE_MILLIS)
} else if (pendingFrames.isNotEmpty()) {
Thread.sleep(BUSY_MILLIS)
}
}
} finally {
// Captures are answered before any GL teardown, which can itself throw: a caller awaiting one must
// hear back however this thread ends.
acceptingSnapshots = false
failPendingSnapshots()
// glFinish before any other GL call here, so the driver completes all pending GPU work BEFORE the
// disposers delete GL objects and the context is destroyed - otherwise a driver worker thread can be
// mid-copy on memory we free, which crashed (SIGSEGV in libc memcpy) on a clean window close. A
// single barrier here; the collaborators' dispose() must NOT call glFinish, and the context is
// destroyed last.
GL11.glFinish()
// Abandon in-flight read-backs (the fences/staging are freed through the device); the surface
// targets go the same way. The context is destroyed last.
while (pendingFrames.isNotEmpty()) {
device.cancelReadback(pendingFrames.removeFirst().ticket)
}
// The renderer's own device objects. Source artwork and underlay images are created and
// destroyed across its life rather than uploaded once, so they need releasing explicitly
// rather than being left to die with the context.
renderer.disposeGl()
pendingRasterBatches.clear()
surface.dispose()
context.destroy()
}
}
/**
* The resize-throttle gate: whether a render whose ONLY staleness is its size should wait. A size
* that has held still for the settle window renders immediately (the full-quality settle pass);
* one still in motion renders at most once per throttle interval.
*
* @param AreaSlot slot The area being considered.
* @param Long nowNanos The loop pass's monotonic timestamp.
* @return Boolean True to skip this tick and let the idle sleep revisit.
*/
private fun shouldDeferResizeRender(slot: AreaSlot, nowNanos: Long): Boolean {
val settled = nowNanos - slot.sizeChangedNanos >= RESIZE_SETTLE_NANOS
val throttleElapsed = nowNanos - slot.resizeRenderNanos >= RESIZE_THROTTLE_NANOS
return !settled && !throttleElapsed
}
/**
* Renders [slot] at [width] x [height] into the supersampled draw target, box-downscales it into the
* resolve framebuffer, then kicks off an asynchronous read-back gated by a fence. Marks the slot
* in-flight; the result is posted later by [collectCompleted].
*
* @param String areaId The area's id.
* @param AreaSlot slot The area being rendered.
* @param Int width The render width in pixels.
* @param Int height The render height in pixels.
* @param Long paramsVersion The pose version this render reflects.
* @param ViewportCamera camera The view to project through.
* @param PuppetModel orderModel The model whose geometry this render reflects (stamped onto the frame).
* @param Int renderScale Framebuffer pixels per display pixel for THIS render: the settle scale for
* a still frame, the interactive scale while the size is in motion.
*/
private fun issueRender(
areaId: String,
slot: AreaSlot,
width: Int,
height: Int,
paramsVersion: Long,
camera: ViewportCamera,
orderModel: PuppetModel,
renderScale: Int,
) {
val renderWidth = width * renderScale
val renderHeight = height * renderScale
val drawTarget = surface.ensure(width, height, renderScale)
// Supersample: render the whole pipeline (puppet, clip masks, grid) into the renderScale x draw
// buffer, then box-downscale to display size on resolve. The camera zoom and the grid line width scale
// by the same factor so framing and backdrop are unchanged after the downscale. The resolve target
// is display-size whatever the scale, so read-back consumers never see the quality switch.
renderer.setRenderScale(renderScale.toFloat())
// Capture the backdrop versions applied to this render so the freshness stamp below matches what was
// actually drawn; a change after this point bumps them again and re-renders next iteration.
val puppetRenderBumpDone = puppetRenderBump
val atlasRenderBumpDone = atlasRenderBump
val gridConfigApplied = gridConfigBacking
renderer.setGrid(gridColorsBacking, gridConfigApplied.scale, gridConfigApplied.subdivisions)
renderer.setSelection(selectionBacking)
renderer.setActiveSelection(activeSelectionBacking)
// The shown set is applied in the render-loop pose block (before setPose filters the draw list by it).
renderer.setSelectionHighlightColor(highlightRed, highlightGreen, highlightBlue)
renderer.setActiveSelectionHighlightColor(activeHighlightRed, activeHighlightGreen, activeHighlightBlue)
renderer.setCamera(camera.copy(zoom = camera.zoom * renderScale))
// Read once, drawn and stamped from the same value: re-reading slot.uvContent between the draw and
// the stamp below would let a switch land in between and mark the frame fresh for content it does
// not show.
val uvContent = slot.uvContent
when (slot.scene) {
RenderScene.Puppet2D -> renderer.render(drawTarget, renderWidth, renderHeight)
// A UV area draws its flat surface instead; the pose / selection / shown state pushed above are
// harmless no-ops for it (neither UV draw reads any of them - just the grid and the surface quad).
RenderScene.UvScene ->
when (uvContent) {
// An atlas page the engine already uploaded, addressed by index.
is UvSceneContent.AtlasPage -> renderer.renderAtlasPage(drawTarget, uvContent.pageIndex, renderWidth, renderHeight)
// Artwork the engine has never uploaded, so the renderer takes the pixels rather than an
// index and caches the texture it makes from them.
is UvSceneContent.SourceLayer -> renderer.renderUnderlayImage(drawTarget, uvContent.image, renderWidth, renderHeight)
null -> renderer.renderAtlasPage(drawTarget, null, renderWidth, renderHeight)
}
}
surface.resolve()
if (!dumped) {
System.getenv("UMAMO_DUMP_PNG")?.let { dumpPath ->
// A synchronous client read-back; safe here because no PBO is bound yet. Encoding and the
// file write live here rather than in :render - reading pixels is the renderer's business,
// turning them into a PNG on disk is not, and keeping the split means :render needs no
// image library at all.
File(dumpPath).writeBytes(PngCodec.write(device.readPixels(surface.resolveTarget, width, height)))
dumped = true
UmamoLog.info("[GL] puppet dumped to $dumpPath (${width}x$height)")
}
}
// Bind the frame to the camera it was rendered at (the plain, non-supersampled camera) and to
// orderModel, the geometry this render reflects, so the overlay projects/poses against them - keeping
// the mesh glued to the raster along both the navigation and edit axes. The resolve target is
// capacity-sized (grow-only), so the read-back covers only the used region.
pendingFrames.addLast(PendingFrame(device.beginReadback(surface.resolveTarget, width, height), areaId, camera, orderModel))
slot.inFlight = true
slot.renderedWidth = width
slot.renderedHeight = height
slot.renderedScale = renderScale
slot.renderedParamsVersion = paramsVersion
slot.renderedCamera = camera
slot.puppetRenderBumpDone = puppetRenderBumpDone
slot.atlasRenderBumpDone = atlasRenderBumpDone
slot.renderedUvContent = uvContent
}
/**
* Collects every read-back whose fence signaled and publishes it to its area's slot, clearing the slot's
* in-flight flag. A read-back whose slot was unregistered while in flight is discarded (the slot is gone).
*/
private fun collectCompleted() {
// Front-first, stopping at the first still-in-flight ticket: reads complete in submission order on
// the GPU timeline, so a later one cannot be done before an earlier one.
while (pendingFrames.isNotEmpty()) {
val pending = pendingFrames.first()
val pixels = device.pollReadback(pending.ticket) ?: break
pendingFrames.removeFirst()
val slot = registry.areas[pending.areaId] ?: continue
slot.inFlight = false
// The device's read-back is TOP-first RGBA already; the preview background is composited into
// RGB, so it is opaque - the shared seam's Opaque path ignores the alpha bytes (no per-frame
// alpha pass) and gives the eventual Android viewport the same conversion for free.
val bitmap = rgbaToImageBitmap(pixels.rgba, pixels.width, pixels.height, RgbaAlphaType.Opaque)
slot.imageState.value = RenderedFrame(bitmap, pending.camera, pending.model)
}
}
/**
* The content rectangle an area's camera fits: the puppet's rest-pose bounds for a 2D area, or the
* shown surface's rectangle for a UV-editor area (the atlas page, or the source layer's raster), which
* the registry widens to the shown meshes. Takes the kind and content the registry read rather than
* re-reading the slot, so the rectangle is of the surface the camera is filed under. Render thread only
* (reads the renderer's bounds).
*
* @param RenderScene scene The area's kind.
* @param UvSceneContent? uvContent What a UV-editor area shows; null for a puppet area.
* @return ContentBounds The rectangle to fit.
*/
private fun contentBoundsFor(scene: RenderScene, uvContent: UvSceneContent?): ContentBounds =
when (scene) {
RenderScene.Puppet2D -> renderer.contentBounds()
RenderScene.UvScene ->
when (uvContent) {
is UvSceneContent.AtlasPage -> pageContentBounds(uvContent.pageIndex)
is UvSceneContent.SourceLayer -> imageContentBounds(uvContent.image)
null -> pageContentBounds(null)
}
}
/**
* The source-layer rectangle (0, 0, width, height) for the UV-editor fit, or a unit square when there
* is no layer, matching [pageContentBounds]' fallback so both UV scenes frame the same way.
*
* @param DecodedImage image The layer raster, or null for none.
* @return ContentBounds The layer rectangle, in texel/display units.
*/
private fun imageContentBounds(image: DecodedImage?): ContentBounds =
if (image != null) {
ContentBounds(0f, 0f, image.width.toFloat(), image.height.toFloat())
} else {
ContentBounds(0f, 0f, 1f, 1f)
}
/**
* The atlas page rectangle (0, 0, pageWidth, pageHeight) for the UV-editor fit, or a unit square when
* the page is missing (an untextured active drawable) so the fit stays sane and the grid still frames.
*
* @param Int pageIndex The atlas page, or null for none.
* @return ContentBounds The page rectangle, in texel/display units.
*/
private fun pageContentBounds(pageIndex: Int?): ContentBounds {
val page = pageIndex?.let { appliedAtlasBinding.textures.atlases.getOrNull(it) }
return if (page != null) {
ContentBounds(0f, 0f, page.width.toFloat(), page.height.toFloat())
} else {
ContentBounds(0f, 0f, 1f, 1f)
}
}
}
/**
* One render-loop tick's model/pages pairing decision.
*
* @property PuppetModel orderModel The model to render this tick (the published one, or the
* previous one while its pages are still in flight).
* @property AtlasPageBinding? applyBinding The binding to apply before the model, or null.
*/
internal class AtlasPairingDecision(
val orderModel: PuppetModel,
val applyBinding: AtlasPageBinding?,
)
/**
* Decides how the render loop takes up a published model and a published page binding as one
* consistent pair.
*
* The two arrive on independent channels, and on an undo the baseline model would land frames before
* the baseline pages - repacked pixels under baseline coordinates - so an atlas-CHANGING model waits
* until the binding composed for its atlas has arrived, and the loop keeps rendering the previous
* pair. Non-atlas edits pass untouched: their atlas is the applied binding's own instance. Atlas
* comparison is identity first, then equality - the session's baseline short-circuit can publish the
* baseline pages under an equal-but-distinct atlas instance.
*
* Pure and render-thread-agnostic so the hold/apply matrix is testable without a GL context.
*
* @param PuppetModel publishedModel The latest model the UI published.
* @param AtlasPageBinding publishedBinding The latest page binding the UI published.
* @param AtlasPageBinding appliedBinding The binding the renderer currently holds.
* @param PuppetModel? lastModel The model the loop last applied, or null on the first tick.
* @return AtlasPairingDecision What to render and whether to swap pages first.
*/
internal fun resolveAtlasPairing(
publishedModel: PuppetModel,
publishedBinding: AtlasPageBinding,
appliedBinding: AtlasPageBinding,
lastModel: PuppetModel?,
): AtlasPairingDecision {
val bindingMatchesPublished =
publishedBinding.atlas === publishedModel.atlas || publishedBinding.atlas == publishedModel.atlas
val appliedMatchesPublished =
appliedBinding.atlas === publishedModel.atlas || appliedBinding.atlas == publishedModel.atlas
val orderModel =
if (!appliedMatchesPublished && !bindingMatchesPublished) {
// The pages for this model's atlas have not arrived; keep the previous pair. The first
// tick has no previous model to keep, and renders the published one against whatever pages
// exist rather than nothing at all.
lastModel ?: publishedModel
} else {
publishedModel
}
val applyBinding =
if (publishedBinding !== appliedBinding &&
(publishedBinding.atlas === orderModel.atlas || publishedBinding.atlas == orderModel.atlas)
) {
publishedBinding
} else {
null
}
return AtlasPairingDecision(orderModel, applyBinding)
}
@@ -0,0 +1,659 @@
package org.umamo.editor.desktop.viewport
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import org.umamo.render.ContentBounds
import org.umamo.render.ViewportCamera
import org.umamo.ui.viewport.AreaCameraKey
import org.umamo.ui.viewport.CameraSurface
import org.umamo.ui.viewport.RenderedFrame
import org.umamo.ui.viewport.UvSceneContent
import java.util.concurrent.ConcurrentHashMap
/**
* Which content an area renders: the posed puppet (2D viewport), or the UV editor's flat surface.
*
* WHICH flat surface - a packed atlas page or a source layer's artwork - is not recorded here. That
* belongs to [AreaSlot.uvContent], which carries the kind together with its payload; splitting it
* across two fields is what let a switch be observed half applied.
*/
internal enum class RenderScene {
Puppet2D,
UvScene,
}
/** The surface a scene's camera frames, which is what a remembered camera is keyed by beside its area. */
internal val RenderScene.cameraSurface: CameraSurface
get() =
when (this) {
RenderScene.Puppet2D -> CameraSurface.Viewport
RenderScene.UvScene -> CameraSurface.Uv
}
/**
* Which flat surface a UV-editor camera frames: one atlas page, or one source layer. A view of one means
* nothing over another - a page of thousands of texels and a layer of a few hundred share only their
* origin - so a UV-editor area keeps a view per surface.
*/
internal sealed interface UvSurfaceId {
/**
* An atlas page, by index.
*
* @property Int? pageIndex The page, or null for the untextured fallback's unit square.
*/
data class Page(val pageIndex: Int?) : UvSurfaceId
/**
* A source layer, by its key in the document's source-art store.
*
* @property String layerKey The layer's key.
*/
data class Layer(val layerKey: String) : UvSurfaceId
}
/** The surface this content shows: its identity, never its pixels, so a re-decoded layer is the same surface. */
internal val UvSceneContent.surfaceId: UvSurfaceId
get() =
when (this) {
is UvSceneContent.AtlasPage -> UvSurfaceId.Page(pageIndex)
is UvSceneContent.SourceLayer -> UvSurfaceId.Layer(layerKey)
}
/**
* A camera together with the UV surface it frames, published as ONE value so the two cannot tear: a pan on the
* UI thread racing a surface switch on the render thread can lose one update at worst, never file a view under
* the wrong surface.
*
* @property ViewportCamera camera The pan / zoom.
* @property UvSurfaceId? surface The UV surface it frames, or null for a puppet area's view of the world.
*/
internal data class FramedCamera(val camera: ViewportCamera, val surface: UvSurfaceId?)
/**
* What a UV-editor view is remembered under for the session: one area showing one surface.
*
* @property String areaId The hosting leaf's area id.
* @property UvSurfaceId surface The page or layer the view frames.
*/
internal data class AreaUvSurfaceKey(val areaId: String, val surface: UvSurfaceId)
/**
* The rectangle a UV-editor fit frames: the shown surface, widened to take in every shown mesh that reaches
* past it. A placement moved off the page carries its islands with it, and a fit that only knew the page
* would frame everything but the thing just moved.
*
* @param ContentBounds surfaceBounds The shown surface's rectangle.
* @param ContentBounds? islandExtent The shown meshes' bounds, or null for none.
* @return ContentBounds The union of the two.
*/
internal fun uvFitBounds(surfaceBounds: ContentBounds, islandExtent: ContentBounds?): ContentBounds {
if (islandExtent == null) {
return surfaceBounds
}
val minX = minOf(surfaceBounds.minX, islandExtent.minX)
val minY = minOf(surfaceBounds.minY, islandExtent.minY)
val maxX = maxOf(surfaceBounds.minX + surfaceBounds.width, islandExtent.minX + islandExtent.width)
val maxY = maxOf(surfaceBounds.minY + surfaceBounds.height, islandExtent.minY + islandExtent.height)
return ContentBounds(minX, minY, maxX - minX, maxY - minY)
}
/** The camera and pixel size of a registered area, resolved for a CPU pick. Null-camera areas do not appear. */
internal data class AreaView(val camera: ViewportCamera, val width: Int, val height: Int)
/**
* Per-area render state, shared between the UI thread ([ViewportAreaRegistry]) and the render thread
* ([OffscreenRenderEngine]). Field-ownership contract:
*
* - The @Volatile fields are written by the UI thread and read by the render thread (a volatile publish of
* immutable values or plain scalars): scene, uvContent, uvIslandExtent, width, height, refitRequested.
* framing is written by both: the UI thread's pan / zoom and the render thread's establish, each
* replacing the whole value.
* - imageState / cameraState are thread-safe StateFlows; either thread may set them.
* - refCount is touched only on the UI thread (register/unregister run as composition effects).
* - The remaining plain fields (inFlight, rendered*, *RenderBumpDone) are render-thread-only bookkeeping.
*/
internal class AreaSlot {
// Whether this area renders the posed puppet or the UV editor's flat surface. Set by whichever
// registration claimed the slot last (register vs registerUvScene): switching an area's editor type in
// place registers the new space before the old one releases, so a live slot CAN change kind. WHICH
// flat surface is carried by uvContent below. UI thread writes, render thread reads - a volatile publish.
@Volatile
var scene: RenderScene = RenderScene.Puppet2D
// What a UV-editor area draws, as ONE value: which kind and its payload inseparably.
//
// Publishing the kind and the payload as separate fields would let the render thread observe a
// half-applied switch - the old kind against the new payload - which reads as a legitimately stale
// frame, renders grid-only, and then stamps itself fresh against the payload that landed meanwhile.
// The area would sit on an empty grid until a pan or resize happened to dislodge it, and nothing
// would look wrong anywhere. A single reference cannot tear, so the switch is all-or-nothing.
//
// Null for a puppet area, which has no UV surface.
@Volatile
var uvContent: UvSceneContent? = null
// The display-space bounds of the meshes a UV-editor area shows, which its fit widens the surface to take
// in. Read only when a fit runs, so an edit that moves an island re-renders nothing. Written BEFORE
// uvContent, and read after it: a render thread that sees new content also sees the extent measured over it.
@Volatile
var uvIslandExtent: ContentBounds? = null
@Volatile
var width: Int = 0
@Volatile
var height: Int = 0
val imageState = MutableStateFlow<RenderedFrame?>(null)
// The per-area camera (pan/zoom) with the UV surface it frames. null until the render thread computes the
// initial fit (it needs the area size + content bounds); thereafter each pan / zoom swaps in a new immutable
// value (a volatile publish), and the render thread swaps it again when a UV area's shown surface is no
// longer the one it frames. cameraState mirrors the camera for the overlay readout.
@Volatile
var framing: FramedCamera? = null
/** The area's current pan / zoom, or null before the first fit. */
val camera: ViewportCamera?
get() = framing?.camera
// Set by the Fit command (UI thread), cleared by the render thread, which then recomputes a fresh fit
// (ignoring any remembered camera). A flag rather than camera=null so the old view shows until the refit
// lands, and so refit beats the workspace-restore path.
@Volatile
var refitRequested: Boolean = false
val cameraState = MutableStateFlow<ViewportCamera?>(null)
// How many live composables currently hold this area id. A leaf can be torn down and rebuilt for the SAME
// id during a tree collapse (closing a split sibling), so register(new) and unregister(old) briefly
// overlap; the slot is dropped only when this returns to 0. Touched only on the Compose UI thread.
var refCount: Int = 0
// Render-thread-only bookkeeping (no synchronization needed).
var inFlight: Boolean = false
var renderedWidth: Int = -1
var renderedHeight: Int = -1
var renderedParamsVersion: Long = -1
var renderedCamera: ViewportCamera? = null
var puppetRenderBumpDone: Long = -1
var atlasRenderBumpDone: Long = -1
var renderedUvContent: UvSceneContent? = null
// Render-thread-only resize-throttle bookkeeping: the last size the loop observed, when it last
// changed, when the last resize-driven render was issued (all System.nanoTime), and the
// supersample scale of the last issued render (a 1x interactive frame stays size-stale so the
// settle pass re-renders it at full quality).
var observedWidth: Int = 0
var observedHeight: Int = 0
var sizeChangedNanos: Long = 0L
var resizeRenderNanos: Long = 0L
var renderedScale: Int = -1
}
/**
* Owns the registered viewport areas and their cameras. The register/resize/camera-navigation surface runs
* on the UI thread; [OffscreenRenderEngine] iterates the same [areas] map on the render thread and calls
* [establishCamera] to fit newly-sized areas. The shared state is safe across the two threads: the slot map
* is a ConcurrentHashMap, per-area hand-off fields are @Volatile, and the camera flows are StateFlows.
*/
internal class ViewportAreaRegistry {
/** The registered areas, keyed by stable area id. Iterated by the render engine; mutated by the UI thread. */
val areas = ConcurrentHashMap<String, AreaSlot>()
// Cameras remembered by area AND surface beyond a slot's composable life, so switching workspaces (which
// disposes the inactive workspace's viewports -> drops their slots) and returning restores the pan/zoom
// instead of refitting. Keyed by the surface too because a view of the puppet's world means nothing over
// a texture's pixels: an area switched between the 2D viewport and the UV editor keeps one view of each.
// Area ids are minted once and never reused, so entries never collide; the map grows only by areas ever
// shown (a few floats each) and is not evicted (session-bounded, negligible cost). A UV editor's entry is
// the view of the page or layer it shows now - the one a save writes.
private val rememberedCameras = ConcurrentHashMap<AreaCameraKey, ViewportCamera>()
// A UV-editor area's view of EACH page and layer it has shown, so switching to one it has left brings back
// that view and one it has never shown is fitted: a page's pan and zoom over a layer a fraction of its size
// lands the layer tiny and in a corner. Session state only - never in cameras(), so it never reaches a
// save - and dropped with the engine, so a new document starts over. Bounded the way rememberedCameras is.
private val uvSurfaceCameras = ConcurrentHashMap<AreaUvSurfaceKey, ViewportCamera>()
// The areas that have shown a UV surface this session. Until an area has, its remembered UV view can only
// be the one the document was saved with, which belongs to whichever surface the area opens on.
private val uvShownAreaIds = ConcurrentHashMap.newKeySet<String>()
/**
* Every remembered camera, by area and surface - the areas shown now and the ones a workspace switch put away.
*
* @return Map A copy of the remembered cameras.
*/
fun cameras(): Map<AreaCameraKey, ViewportCamera> = HashMap(rememberedCameras)
/**
* Remembers [cameras] as though each area had been shown with it, so an area registering for the first time
* opens on its saved view rather than a fit. Meant for the moment the engine is built, before any area
* registers; an area that already has a camera keeps it.
*
* @param Map cameras The saved cameras, by area and surface.
*/
fun seedCameras(cameras: Map<AreaCameraKey, ViewportCamera>) {
for ((cameraKey, camera) in cameras) {
rememberedCameras.putIfAbsent(cameraKey, camera)
}
}
// Zoom increments in percentage points, fed from settings (viewport.zoomStep*Percent): the fine step is
// one wheel notch / keyboard press, the coarse step is the Shift-held variant. Defaults mirror
// defaultSettings.json. UI thread only.
@Volatile
var zoomStepPercent: Float = 1f
@Volatile
var zoomStepCoarsePercent: Float = 5f
/**
* Registers a viewport area and returns the flow of images to display for it. Re-registering an id that
* is still live (the same area's leaf rebuilt during a tree collapse - see [AreaSlot.refCount]) returns
* the existing slot and its last image, so the surviving viewport keeps rendering instead of being
* orphaned.
*
* @param String areaId The hosting area's stable id.
* @return StateFlow The area's image stream (null until the first render completes).
*/
fun register(areaId: String): StateFlow<RenderedFrame?> {
val slot = areas.getOrPut(areaId) { AreaSlot() }
claim(slot, RenderScene.Puppet2D, content = null, islandExtent = null)
slot.refCount++
return slot.imageState
}
/**
* Registers a UV-editor area (the flat image underlay) and returns its image flow.
*
* @param String areaId The hosting area's stable id.
* @param UvSceneContent content What the area draws.
* @param ContentBounds? islandExtent The shown meshes' display-space bounds, or null for none.
* @return StateFlow The area's image stream (null until the first render completes).
*/
fun registerUvScene(areaId: String, content: UvSceneContent, islandExtent: ContentBounds?): StateFlow<RenderedFrame?> {
val slot = areas.getOrPut(areaId) { AreaSlot() }
claim(slot, RenderScene.UvScene, content, islandExtent)
slot.refCount++
return slot.imageState
}
/**
* Makes [slot] an area of [scene], whatever it was.
*
* A slot outlives the space that registered it whenever the next space registers first - and switching an
* area's editor type in place does exactly that, the new space composing before the old one is disposed. The
* slot then holds the OLD kind, its surface, and its camera, so a registration has to claim all three or the
* engine keeps drawing the UV page under a 2D viewport's gizmos (and frames the puppet with a page's pan and
* zoom). A registration of the same kind - a leaf rebuilt during a tree collapse - changes nothing here, so
* the surviving viewport keeps its view.
*
* Order matters to the render thread, which walks the slot map and can see this slot mid-claim. Becoming a
* UV scene, the content goes first and the kind second; becoming a puppet, the kind goes first and the
* content is cleared second - either way the area never reads as a UV scene with nothing to draw. The camera
* goes LAST: dropped before the kind, the render thread could re-establish the old surface's view in the gap
* and keep it. Dropped after, the worst it can do is render one frame of the new surface through the old
* camera, which the fresh camera then makes stale.
*
* @param AreaSlot slot The slot to claim.
* @param RenderScene scene The kind of area registering.
* @param UvSceneContent? content What a UV area draws; null for a puppet area.
* @param ContentBounds? islandExtent The shown meshes' bounds a UV area's fit takes in; null for a puppet area.
*/
private fun claim(slot: AreaSlot, scene: RenderScene, content: UvSceneContent?, islandExtent: ContentBounds?) {
val kindChanged = slot.scene != scene
when (scene) {
RenderScene.UvScene -> {
slot.uvIslandExtent = islandExtent
slot.uvContent = content
slot.scene = scene
}
RenderScene.Puppet2D -> {
slot.scene = scene
slot.uvContent = null
slot.uvIslandExtent = null
}
}
if (kindChanged) {
// The old surface's view stays remembered under its own key for the day the area switches back; this
// one is re-established from the new surface's remembered view, or a fit. The last frame goes too:
// it shows the old surface, and the new space's overlays would be drawn over it until the next lands.
slot.framing = null
slot.cameraState.value = null
slot.imageState.value = null
}
}
/**
* Retargets what an already-registered UV-editor area draws, and the mesh extent its fit takes in. A no-op
* for an unregistered area or a puppet (2D) area - only a registration moves an area between the puppet and
* the UV family, and this moves the content within the UV one.
*
* A switch to another page or layer changes no camera here: the render thread sees that the surface shown is
* no longer the one the camera frames and swaps the view as it establishes the next frame, so the new
* surface's first frame already renders through its own view (see [establishCamera]).
*
* @param String areaId The UV-editor area to retarget.
* @param UvSceneContent content The new content to draw.
* @param ContentBounds? islandExtent The shown meshes' display-space bounds, or null for none.
*/
fun setUvSceneContent(areaId: String, content: UvSceneContent, islandExtent: ContentBounds?) {
val slot = areas[areaId] ?: return
if (slot.scene == RenderScene.Puppet2D) {
return
}
applyUvContent(slot, content, islandExtent)
}
/**
* Publishes one UV content choice onto a slot, kind and payload inseparably, with the mesh extent measured
* over it.
*
* The content is one volatile store of one immutable value, which is what makes the switch atomic - see
* [AreaSlot.uvContent] for what publishing them separately would cost. The extent goes first, so a render
* thread that sees the new content also sees the extent that belongs to it.
*
* @param AreaSlot slot The slot to retarget.
* @param UvSceneContent content What the area draws.
* @param ContentBounds? islandExtent The shown meshes' display-space bounds, or null for none.
*/
private fun applyUvContent(slot: AreaSlot, content: UvSceneContent, islandExtent: ContentBounds?) {
slot.uvIslandExtent = islandExtent
slot.uvContent = content
}
/**
* Releases one hold on an area; the slot is dropped only when the last holder leaves (ref-count to zero).
* This guards the tree-collapse case: closing one split sibling rebuilds the surviving area's leaf under a
* fresh composition node, so its [register] runs BEFORE the old leaf's unregister - a plain remove here
* would delete the slot the rebuilt viewport just bound to, freezing it at a stale (stretched) frame. Any
* read-back already in flight for a truly-dropped slot still completes and is discarded when collected.
*
* @param String areaId The area id to release.
*/
fun unregister(areaId: String) {
val slot = areas[areaId] ?: return
slot.refCount--
if (slot.refCount <= 0) {
areas.remove(areaId)
}
}
/**
* Returns the flow of the area's current camera, for the overlay zoom readout. The viewport composable
* registers the area before reading this, so it attaches to the existing slot.
*
* @param String areaId The area id.
* @return StateFlow The area's camera stream (null until the first fit).
*/
fun cameraFlow(areaId: String): StateFlow<ViewportCamera?> =
areas.getOrPut(areaId) { AreaSlot() }.cameraState
/**
* Updates an area's requested pixel size; the render thread re-renders it at the new size. A no-op for an
* unregistered id - registration always precedes the size report, so resize must never resurrect a slot
* the ref-count has already dropped (that would leak a zero-ref slot the render loop renders forever).
*
* @param String areaId The area id.
* @param Int width The new width in pixels.
* @param Int height The new height in pixels.
*/
fun resize(areaId: String, width: Int, height: Int) {
val slot = areas[areaId] ?: return
slot.width = width
slot.height = height
}
/**
* Pans the area's camera by a screen-pixel drag (grab style). No-op before the initial fit exists.
*
* @param String areaId The area id.
* @param Float deltaXpx Horizontal drag in pixels.
* @param Float deltaYpx Vertical drag in pixels.
*/
fun pan(areaId: String, deltaXpx: Float, deltaYpx: Float) {
updateCamera(areaId) { camera -> camera.panByScreen(deltaXpx, deltaYpx) }
}
/**
* Zooms the area's camera about a cursor position (wheel zoom) by one configured step, pinning the world
* point under the cursor. The step (fine or coarse Shift step) comes from settings.
*
* @param String areaId The area id.
* @param Boolean zoomIn True to zoom in, false to zoom out.
* @param Boolean coarse Use the coarse (Shift) step.
* @param Float cursorXpx Cursor X in pixels.
* @param Float cursorYpx Cursor Y in pixels.
*/
fun zoomAtCursor(areaId: String, zoomIn: Boolean, coarse: Boolean, cursorXpx: Float, cursorYpx: Float) {
val slot = areas[areaId] ?: return
val width = slot.width
val height = slot.height
val step = stepFor(coarse)
val deltaPercent = if (zoomIn) step else -step
updateCamera(areaId) { camera ->
camera.zoomAtCursorByPercent(
deltaPercent,
step,
cursorXpx,
cursorYpx,
width,
height,
)
}
}
/**
* Frames a screen-pixel rectangle in the area's camera (Zoom Region / Shift+B): the box fills the
* viewport, letterboxed on the looser axis. A no-op before the first fit or when the area has no size yet.
*
* @param String areaId The area id.
* @param Float leftPx One horizontal box edge in viewport pixels.
* @param Float topPx One vertical box edge in viewport pixels.
* @param Float rightPx The other horizontal box edge in viewport pixels.
* @param Float bottomPx The other vertical box edge in viewport pixels.
*/
fun zoomToRegion(areaId: String, leftPx: Float, topPx: Float, rightPx: Float, bottomPx: Float) {
val slot = areas[areaId] ?: return
val width = slot.width
val height = slot.height
if (width <= 0 || height <= 0) {
return
}
updateCamera(areaId) { camera -> camera.framingScreenRect(leftPx, topPx, rightPx, bottomPx, width, height) }
}
/**
* Zooms the area's camera about its center (keyboard zoom in/out) by one configured step.
*
* @param String areaId The area id.
* @param Boolean zoomIn True to zoom in, false to zoom out.
* @param Boolean coarse Use the coarse (Shift) step.
*/
fun zoomCentered(areaId: String, zoomIn: Boolean, coarse: Boolean) {
val step = stepFor(coarse)
val deltaPercent = if (zoomIn) step else -step
updateCamera(areaId) { camera -> camera.zoomedByPercent(deltaPercent, step) }
}
/**
* Sets the area's camera to true 1:1 about its center (actual size / 100%).
*
* @param String areaId The area id.
*/
fun actualSize(areaId: String) {
updateCamera(areaId) { camera -> camera.withActualSize() }
}
/**
* Refits the area's camera to the content on the next render tick by flagging it - the render thread,
* which owns the content bounds and the current size, recomputes the fit in [establishCamera].
*
* @param String areaId The area id.
*/
fun fit(areaId: String) {
val slot = areas[areaId] ?: return
slot.refitRequested = true
}
/**
* Fits a world-space rectangle inside the area, centerd (the Frame Selected camera move). A no-op before
* the first fit or when the area has no size yet.
*
* @param String areaId The area id.
* @param Float minX The rectangle's minimum world x.
* @param Float minZ The rectangle's minimum world z (up).
* @param Float maxX The rectangle's maximum world x.
* @param Float maxZ The rectangle's maximum world z (up).
*/
fun fitWorldRect(areaId: String, minX: Float, minZ: Float, maxX: Float, maxZ: Float) {
val slot = areas[areaId] ?: return
val width = slot.width
val height = slot.height
if (width <= 0 || height <= 0 || maxX < minX || maxZ < minZ) {
return
}
// A degenerate rect (a single vertex) still frames: ContentBounds spans are clamped to >= 1 world unit
// by the fit, so the camera centers on the point at a sane zoom.
updateCamera(areaId) {
ViewportCamera.fit(ContentBounds(minX, minZ, maxX - minX, maxZ - minZ), width, height)
}
}
/**
* The camera and size of an area for a CPU pick, or null when the area is unregistered, unsized, or has
* no camera yet (before the first fit).
*
* @param String areaId The area id.
* @return AreaView The area's camera and pixel size, or null.
*/
fun viewFor(areaId: String): AreaView? {
val slot = areas[areaId] ?: return null
val camera = slot.camera ?: return null
return AreaView(camera, slot.width, slot.height)
}
/**
* Render-thread: ensures the slot has a camera for what it shows, establishing or refitting it now that the
* size is known. A pending refit forces a fresh fit. Otherwise a freshly-(re)registered area restores its
* remembered camera (so workspace switches preserve pan/zoom), and a UV-editor area whose shown page or
* layer is no longer the one its camera frames swaps to the view it left that surface with - either falling
* back to a fit the first time that surface is shown. The content bounds are resolved lazily (only when a
* fit is actually needed) via [contentBounds]; a UV-editor fit is widened to the shown meshes' extent.
*
* The kind and the content are read once, up front: the fit, the recall, and the record all have to be about
* the same surface, and the UI thread can retarget the slot at any moment. A retarget that lands after the
* read leaves a camera framing a surface no longer shown, which the next call swaps in turn.
*
* @param AreaSlot slot The area being established.
* @param String areaId The area id.
* @param Int width The current area width.
* @param Int height The current area height.
* @param Function contentBounds Supplies the rectangle of the scene and content it is handed, evaluated only
* when a fit is needed.
* @return ViewportCamera The area's current camera.
*/
fun establishCamera(
slot: AreaSlot,
areaId: String,
width: Int,
height: Int,
contentBounds: (RenderScene, UvSceneContent?) -> ContentBounds,
): ViewportCamera {
val scene = slot.scene
val content = slot.uvContent
val shownSurface =
when (scene) {
RenderScene.Puppet2D -> null
RenderScene.UvScene -> content?.surfaceId ?: UvSurfaceId.Page(null)
}
val framing = slot.framing
val refit = slot.refitRequested
if (framing != null && !refit && framing.surface == shownSurface) {
return framing.camera
}
val recalled = if (refit) null else recallCamera(areaId, scene, shownSurface)
val camera =
recalled ?: run {
val sceneBounds = contentBounds(scene, content)
// Read after the content: the UI thread writes the extent first, so it belongs to this content.
val fitBounds =
when (scene) {
RenderScene.Puppet2D -> sceneBounds
RenderScene.UvScene -> uvFitBounds(sceneBounds, slot.uvIslandExtent)
}
ViewportCamera.fit(fitBounds, width, height)
}
slot.refitRequested = false
publishCamera(slot, areaId, FramedCamera(camera, shownSurface))
return camera
}
/**
* The view an area had of a surface, for an area establishing one without a refit, or null when it has none
* and the surface is fitted.
*
* A UV-editor area takes its own view of that page or layer first. The area's whole-UV view - what a saved
* document seeds - stands in only while the area has shown no UV surface this session: until then it can only
* be the saved view, which belongs to whatever surface the area opens on. After that it is the last surface's
* view, and a different surface fits rather than inheriting it.
*
* @param String areaId The area id.
* @param RenderScene scene The area's kind.
* @param UvSurfaceId? surface The UV surface shown, or null for a puppet area.
* @return ViewportCamera? The view to restore, or null to fit.
*/
private fun recallCamera(areaId: String, scene: RenderScene, surface: UvSurfaceId?): ViewportCamera? {
if (surface == null) {
return rememberedCameras[AreaCameraKey(areaId, scene.cameraSurface)]
}
uvSurfaceCameras[AreaUvSurfaceKey(areaId, surface)]?.let { remembered ->
return remembered
}
if (areaId in uvShownAreaIds) {
return null
}
return rememberedCameras[AreaCameraKey(areaId, CameraSurface.Uv)]
}
/**
* Makes [framing] the slot's camera and remembers it: under the area and its surface kind (what a save writes
* and a workspace switch restores) and, for a UV-editor view, under the page or layer it frames. Keyed off the
* framing's own surface rather than the slot's current content, so a view is always filed with the surface it
* was taken of.
*
* @param AreaSlot slot The area's slot.
* @param String areaId The area id.
* @param FramedCamera framing The camera and the surface it frames.
*/
private fun publishCamera(slot: AreaSlot, areaId: String, framing: FramedCamera) {
slot.framing = framing
slot.cameraState.value = framing.camera
val surface = framing.surface
if (surface == null) {
rememberedCameras[AreaCameraKey(areaId, CameraSurface.Viewport)] = framing.camera
} else {
rememberedCameras[AreaCameraKey(areaId, CameraSurface.Uv)] = framing.camera
uvSurfaceCameras[AreaUvSurfaceKey(areaId, surface)] = framing.camera
uvShownAreaIds.add(areaId)
}
}
/** The zoom step in percentage points for this notch/press: the coarse (Shift) step or the fine step. */
private fun stepFor(coarse: Boolean): Float = if (coarse) zoomStepCoarsePercent else zoomStepPercent
/**
* Applies [transform] to the area's current camera and publishes the result, still framing the surface it
* framed. No-op before the initial fit (there is nothing to transform until the first frame establishes the
* view).
*
* @param String areaId The area id.
* @param Function transform Maps the current camera to its replacement.
*/
private fun updateCamera(areaId: String, transform: (ViewportCamera) -> ViewportCamera) {
val slot = areas[areaId] ?: return
val framing = slot.framing ?: return
publishCamera(slot, areaId, framing.copy(camera = transform(framing.camera)))
}
}
@@ -0,0 +1,240 @@
package org.umamo.editor.desktop.viewport
import androidx.compose.ui.graphics.ImageBitmap
import org.umamo.render.PuppetTextures
import org.umamo.render.ViewportCamera
import org.umamo.render.pick.PickCandidate
import org.umamo.render.pick.drawableCentroids
import org.umamo.render.pick.pickAllDrawables
import org.umamo.render.pick.pickDrawable
import org.umamo.render.pick.screenToWorldX
import org.umamo.render.pick.screenToWorldZ
import org.umamo.render.puppet.PuppetRenderer
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.atlasKeyByDrawable
import org.umamo.runtime.model.drawableNameByDrawable
import org.umamo.runtime.model.partNameByDrawable
import org.umamo.runtime.model.pickableIndicesByDrawable
import org.umamo.runtime.model.pickableUvsByDrawable
import org.umamo.ui.model.DrawableThumbnailProvider
import org.umamo.ui.model.DrawableThumbnailer
/**
* CPU-side hit-testing and art previews for the viewport, over the current deformed pose. Runs entirely on
* the UI thread and never touches GL: it reuses the renderer's pure-CPU pick geometry (a snapshot the render
* thread produces) and its resolved draw order, and the retained CPU atlas pixels for the alpha gate. The
* facade resolves each area's camera and size and forwards them here, so this class is area-agnostic.
*
* The model-derived lookup maps (pick indices / UVs, atlas keys, part labels) and the thumbnail provider are
* rebuilt by [updateModel] so session-created drawables (a duplicate's fresh ".001" id) and visibility edits
* stay pickable, sampleable, and labeled - maps frozen at construction would leave a duplicate unpickable.
*
* ビューポートの CPU ヒットテストとアートプレビュー。UI スレッドのみ、GL 不使用。
*
* @property PuppetRenderer renderer The renderer, for its pure-CPU pickGeometry() and drawnOrder().
* @property PuppetTextures textures The atlas pages, for the alpha gate and page sizes.
*/
internal class ViewportPicker(
private val renderer: PuppetRenderer,
// var: the session swaps the page set on a repack, and the alpha gate must sample the pixels the
// GPU is showing - see setTextures.
private var textures: PuppetTextures,
model: PuppetModel,
) {
// Per-drawable triangle indices for hit-testing, restricted to the drawables actually shown (the
// Parts-panel eyeball cascade) and to those carrying a triangle mesh. Picking iterates the pose's
// deformed positions and looks indices up here, so unshown / mesh-less drawables are never hit.
private var pickableIndices: Map<DrawableId, IntArray> = model.pickableIndicesByDrawable()
// Per-drawable UVs (full-atlas [0,1]) for the same pickable set, so picking can interpolate the hit
// point's UV and sample the atlas alpha (rejecting clicks on a mesh's transparent triangle overhang).
private var pickableUvs: Map<DrawableId, FloatArray> = model.pickableUvsByDrawable()
// Drawable id -> owning part name, for the overlap-picker row labels.
private var partNameByDrawableId: Map<DrawableId, String> = model.partNameByDrawable()
// Drawable id -> its own name, the other half of an overlap-picker row label.
private var drawableNameByDrawableId: Map<DrawableId, String> = model.drawableNameByDrawable()
// Drawable id -> atlas lookup key: the source-format id the atlas map is keyed by, resolved through
// textureSourceId so a duplicate samples its SOURCE's texels for the pick alpha gate.
private var atlasKeyByDrawableId: Map<DrawableId, String> = model.atlasKeyByDrawable()
// Art-mesh previews for the overlap picker (the same provider the Outliner hover uses). Pure CPU over
// the immutable atlas bytes, so it is built once and shared - a single cache across both consumers.
private val thumbnailer = DrawableThumbnailer(model, textures)
/**
* Swaps the atlas page set after a repack (or its undo), so the alpha gate and the thumbnails read
* the pixels the viewport is showing rather than the set the picker was built over.
*
* @param PuppetTextures next The new page set.
*/
fun setTextures(next: PuppetTextures) {
if (next === textures) {
return
}
textures = next
thumbnailer.setTextures(next)
}
/**
* Rebuilds the model-derived lookup maps and the thumbnail provider after a committed edit or undo, so
* session-created drawables and visibility edits stay pickable, sampleable, and labeled.
*
* @param PuppetModel model The current model.
*/
fun updateModel(model: PuppetModel) {
pickableIndices = model.pickableIndicesByDrawable()
pickableUvs = model.pickableUvsByDrawable()
partNameByDrawableId = model.partNameByDrawable()
drawableNameByDrawableId = model.drawableNameByDrawable()
atlasKeyByDrawableId = model.atlasKeyByDrawable()
thumbnailer.updateModel(model)
}
/**
* Hit-tests a viewport pixel against the current deformed pose and returns the FRONT-MOST opaque drawable
* under it, or null when the click misses or no pose is ready yet. Restricted to shown, meshed drawables;
* front/back uses the renderer's resolved draw order, and the transparent triangle overhang is rejected
* by the atlas-alpha gate.
*
* @param ViewportCamera camera The area's camera (screen-to-world inverse).
* @param Int width The area width in pixels.
* @param Int height The area height in pixels.
* @param Float cursorXpx Cursor X in pixels (top-left origin).
* @param Float cursorYpx Cursor Y in pixels (top-left origin).
* @return DrawableId The hit drawable, or null on a miss.
*/
fun pickAt(camera: ViewportCamera, width: Int, height: Int, cursorXpx: Float, cursorYpx: Float): DrawableId? {
if (width <= 0 || height <= 0) {
return null
}
val geometry = renderer.pickGeometry() ?: return null
// Screen (y-down) to world (y-up), the inverse of the camera's worldToNdc - see ScreenSpacePick.
val worldX = screenToWorldX(cursorXpx, camera, width)
val worldZ = screenToWorldZ(cursorYpx, camera, height)
return pickDrawable(
worldX,
worldZ,
geometry.worldPositions,
pickableIndices,
pickableUvs,
frontRankMap(),
::sampleTexelAlpha,
)
}
/**
* All opaque drawables under a viewport pixel, FRONT-TO-BACK with each one's centrality - for the
* Alt-click overlap-picker popup. Same screen-to-world, hit, and alpha gate as [pickAt].
*
* @param ViewportCamera camera The area's camera.
* @param Int width The area width in pixels.
* @param Int height The area height in pixels.
* @param Float cursorXpx Cursor X in pixels (top-left origin).
* @param Float cursorYpx Cursor Y in pixels (top-left origin).
* @return List The opaque candidates, front-to-back.
*/
fun pickAllAt(
camera: ViewportCamera,
width: Int,
height: Int,
cursorXpx: Float,
cursorYpx: Float,
): List<PickCandidate> {
if (width <= 0 || height <= 0) {
return emptyList()
}
val geometry = renderer.pickGeometry() ?: return emptyList()
val worldX = screenToWorldX(cursorXpx, camera, width)
val worldZ = screenToWorldZ(cursorYpx, camera, height)
return pickAllDrawables(
worldX,
worldZ,
geometry.worldPositions,
pickableIndices,
pickableUvs,
frontRankMap(),
::atlasSizeOf,
::sampleTexelAlpha,
)
}
/**
* Every visible drawable's world-space centroid at the current pose, for Object-mode region select. Reads
* the same posed pick geometry as [pickAt] and reduces each drawable to its centroid; empty before the
* first frame's geometry lands. Area-independent - the caller projects with its camera.
*
* @return Map The per-drawable [x, y] world centroid.
*/
fun drawableWorldCentroids(): Map<DrawableId, FloatArray> {
val geometry = renderer.pickGeometry() ?: return emptyMap()
return drawableCentroids(geometry.worldPositions)
}
/**
* A small preview of a drawable's art for the overlap-picker popup, delegated to the shared thumbnailer
* (the same provider the Outliner hover uses). Returns null for an untextured or mesh-less drawable.
*
* @param DrawableId id The drawable to preview.
* @return ImageBitmap The cropped preview, or null when untextured or mesh-less.
*/
fun thumbnailFor(id: DrawableId): ImageBitmap? = thumbnailer.thumbnailFor(id)
/** The shared art-mesh thumbnail provider, exposed so the host can wire it to the Outliner hover preview. */
fun thumbnails(): DrawableThumbnailProvider = thumbnailer
/**
* The name of the part a drawable belongs to, for the overlap-picker row labels, or null when the
* drawable sits at the root with no owning part.
*
* @param DrawableId id The drawable to look up.
* @return String The owning part's name, or null.
*/
fun partNameFor(id: DrawableId): String? = partNameByDrawableId[id]
/**
* A drawable's own display name, for the overlap-picker row labels, or null when it is not pickable
* in the current model.
*
* @param DrawableId id The drawable to look up.
* @return String The drawable's name, or null.
*/
fun drawableNameFor(id: DrawableId): String? = drawableNameByDrawableId[id]
/** The renderer's resolved back-to-front draw list as a front-rank map (higher index = more front). */
private fun frontRankMap(): Map<DrawableId, Float> =
renderer.drawnOrder().withIndex().associate { (index, id) -> id to index.toFloat() }
/** The drawable's atlas page size (width, height) in texels, or null when it is untextured. */
private fun atlasSizeOf(id: DrawableId): Pair<Int, Int>? =
textures.atlasIndexByDrawableId[atlasKeyByDrawableId[id] ?: id.raw]?.let { atlasIndex ->
textures.atlases.getOrNull(atlasIndex)?.let { image -> image.width to image.height }
}
/**
* The atlas-texel alpha (0..1) for a drawable at a full-atlas (u, v), or 1f when the drawable is
* untextured (a flat draw color, treated as fully opaque). Reads the retained CPU atlas pixels; the
* alpha byte is the coverage whether or not the atlas is premultiplied, so no un-premultiply is needed.
* A point off the page is transparent, as the renderer draws it: a mesh overhangs its art, and when the
* page is a single model image that overhang runs past the page itself.
*
* @param DrawableId id The drawable.
* @param Float u The full-atlas U.
* @param Float v The full-atlas V.
* @return Float The texel alpha, 0..1.
*/
private fun sampleTexelAlpha(id: DrawableId, u: Float, v: Float): Float {
val atlasIndex = textures.atlasIndexByDrawableId[atlasKeyByDrawableId[id] ?: id.raw] ?: return 1f
val image = textures.atlases.getOrNull(atlasIndex) ?: return 1f
if (!(u >= 0f && u < 1f && v >= 0f && v < 1f)) {
return 0f
}
val px = (u * image.width).toInt().coerceAtMost(image.width - 1)
val py = (v * image.height).toInt().coerceAtMost(image.height - 1)
val alpha = image.rgba[(py * image.width + px) * 4 + 3].toInt() and 0xFF
return alpha / 255f
}
}
@@ -0,0 +1,181 @@
package org.umamo.editor.desktop.packaging
import org.umamo.editor.desktop.isOpenableDocumentPath
import org.umamo.format.uma.Uma
import org.umamo.format.uma.UmaModel
import org.umamo.format.uma.UmaWriterInfo
import org.w3c.dom.Element
import java.io.ByteArrayOutputStream
import java.io.File
import java.util.zip.CRC32
import java.util.zip.ZipEntry
import java.util.zip.ZipOutputStream
import javax.xml.parsers.DocumentBuilderFactory
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertTrue
/**
* Holds every operating-system registration of the `.uma` type to the codec. The type is declared in four places
* no compiler connects - the freedesktop MIME entry, the desktop entry, the desktop package's build script, and the
* Android manifest - and a registration that names another string, or a magic rule that reads another offset,
* fails silently: the file manager just stops recognising the file. The magic is not compared to a table here,
* it is EVALUATED against the bytes the writer really produces (docs/format/UMA.md § 2).
*/
class OsAssociationFilesTest {
/** Gradle runs a module's tests from the module directory, which is what these paths are relative to. */
private val mimeEntry = File("resources/linux/umamo-uma.xml")
private val desktopEntry = File("resources/linux/umamo.desktop")
private val buildScript = File("build.gradle.kts")
private val androidManifest = File("../android/src/main/AndroidManifest.xml")
/** One `match` rule of a shared-mime-info magic: a string expected at an offset, and the rules nested under it. */
private class MagicRule(val offset: Int, val expected: ByteArray, val nested: List<MagicRule>)
/**
* The bytes a shared-mime-info `string` value denotes: C-style escapes, of which the entry uses the octal form.
*
* @param String value The attribute's text.
* @return ByteArray The bytes to find.
*/
private fun magicBytesOf(value: String): ByteArray {
val bytes = ByteArrayOutputStream()
var position = 0
while (position < value.length) {
if (value[position] == '\\' && position + 3 < value.length && value.substring(position + 1, position + 4).all { digit -> digit in '0'..'7' }) {
bytes.write(value.substring(position + 1, position + 4).toInt(8))
position += 4
} else {
bytes.write(value[position].code)
position++
}
}
return bytes.toByteArray()
}
/**
* The `match` rules directly under [parent], each with its own nested rules.
*
* @param Element parent A `magic` or `match` element.
* @return List<MagicRule> The rules.
*/
private fun rulesUnder(parent: Element): List<MagicRule> {
val rules = ArrayList<MagicRule>()
val children = parent.childNodes
for (childIndex in 0 until children.length) {
val child = children.item(childIndex) as? Element ?: continue
if (child.tagName == "match") {
assertEquals("string", child.getAttribute("type"), "the matcher below only evaluates string rules")
rules += MagicRule(child.getAttribute("offset").toInt(), magicBytesOf(child.getAttribute("value")), rulesUnder(child))
}
}
return rules
}
/**
* Whether [content] satisfies any of [rules]: a rule holds when its bytes sit at its offset AND, when it has
* nested rules, one of those holds too - the shared MIME database's own semantics.
*
* @param ByteArray content The file's bytes.
* @param List<MagicRule> rules The alternatives.
* @return Boolean True when one matches.
*/
private fun matches(content: ByteArray, rules: List<MagicRule>): Boolean =
rules.any { rule ->
val end = rule.offset + rule.expected.size
end <= content.size &&
content.copyOfRange(rule.offset, end).contentEquals(rule.expected) &&
(rule.nested.isEmpty() || matches(content, rule.nested))
}
/** The `mime-type` element of the committed entry. */
private fun mimeTypeElement(): Element {
val document = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(mimeEntry)
return document.getElementsByTagName("mime-type").item(0) as Element
}
/**
* A ZIP whose first entry is a stored `mimetype` holding [mimetype] - the shape KRA, EPUB, and OpenDocument
* share with UMA - or a plain ZIP when [mimetype] is null.
*
* @param String? mimetype The first entry's content, or null for none.
* @return ByteArray The archive.
*/
private fun zipAnnouncing(mimetype: String?): ByteArray {
val bytes = ByteArrayOutputStream()
ZipOutputStream(bytes).use { zip ->
if (mimetype != null) {
val content = mimetype.toByteArray(Charsets.US_ASCII)
val entry = ZipEntry("mimetype")
entry.method = ZipEntry.STORED
entry.size = content.size.toLong()
entry.compressedSize = content.size.toLong()
entry.crc = CRC32().also { crc -> crc.update(content) }.value
zip.putNextEntry(entry)
zip.write(content)
zip.closeEntry()
}
zip.putNextEntry(ZipEntry("content.txt"))
zip.write("not a puppet".toByteArray())
zip.closeEntry()
}
return bytes.toByteArray()
}
/** The magic recognises what the writer writes, and nothing that merely looks like it. */
@Test
fun theFreedesktopMagicMatchesARealUmaAndNothingElse() {
val magic = mimeTypeElement().getElementsByTagName("magic").item(0) as Element
val rules = rulesUnder(magic)
val written = Uma.write(UmaModel.create(UmaWriterInfo("Umamo", "0.0.0-test")))
assertTrue(Uma.matches(written), "the codec's own probe accepts the file")
assertTrue(matches(written, rules), "and so does the freedesktop magic")
assertFalse(matches(zipAnnouncing(null), rules), "a plain ZIP is not a UMA")
assertFalse(matches(zipAnnouncing("application/x-krita"), rules), "nor is another format that announces itself the same way")
// The shared database gives application/zip's bare-signature magic 60 and its ZIP-based formats (EPUB,
// OpenDocument) 70. Above 60 so an extensionless .uma is not read as a plain ZIP; below 80, the level at
// which magic would outrank a file's NAME and a .uma renamed to .zip would stop opening as an archive.
val priority = magic.getAttribute("priority").toInt()
assertTrue(priority in 61..79, "priority $priority must sit above application/zip's 60 and below the name-outranking 80")
}
/** The entry names the codec's type, as a ZIP subtype, with the `.uma` glob. */
@Test
fun theFreedesktopEntryNamesTheCodecsType() {
val mimeType = mimeTypeElement()
assertEquals(Uma.MIME_TYPE, mimeType.getAttribute("type"))
assertEquals("application/zip", (mimeType.getElementsByTagName("sub-class-of").item(0) as Element).getAttribute("type"))
assertEquals("*.${Uma.kind.extension}", (mimeType.getElementsByTagName("glob").item(0) as Element).getAttribute("pattern"))
}
/** The desktop entry, the package's build script, and the Android manifest all name the same type and extension. */
@Test
fun everyRegistrationNamesTheSameType() {
val desktopLines = desktopEntry.readLines()
assertTrue("MimeType=${Uma.MIME_TYPE};" in desktopLines, "the desktop entry handles the type")
assertTrue(desktopLines.any { line -> line.startsWith("Exec=") && line.endsWith("%f") }, "and takes the file as an argument, which Main reads")
val script = buildScript.readText()
assertTrue("val umaMimeType = \"${Uma.MIME_TYPE}\"" in script, "the package's file association names the type")
assertTrue("val umaExtension = \"${Uma.kind.extension}\"" in script, "and the extension")
assertEquals(3, Regex("fileAssociation\\(umaMimeType, umaExtension,").findAll(script).count(), "declared for Windows, macOS, and Linux")
val manifest = androidManifest.readText()
assertTrue("android:mimeType=\"${Uma.MIME_TYPE}\"" in manifest, "the Android intent filter names the type")
assertTrue("android:pathSuffix=\".${Uma.kind.extension}\"" in manifest, "and the extension, for providers that report a generic type")
}
/** A path the OS hands over is accepted by extension alone, however it is cased; the loader checks the content. */
@Test
fun aHandedOverPathIsAcceptedByItsExtension() {
assertTrue(isOpenableDocumentPath("/home/rigger/Erica.uma"))
assertTrue(isOpenableDocumentPath("C:\\Rigs\\ERICA.UMA"))
assertTrue(isOpenableDocumentPath("/home/rigger/Erica.cmo3"))
assertTrue(isOpenableDocumentPath("/home/rigger/Erica.moc3"))
assertFalse(isOpenableDocumentPath("/home/rigger/Erica.psd"), "artwork is imported into a document, never opened as one")
assertFalse(isOpenableDocumentPath("--some-flag"))
}
}
@@ -0,0 +1,123 @@
package org.umamo.editor.desktop.viewport
import org.umamo.render.PuppetTextures
import org.umamo.runtime.model.AtlasPage
import org.umamo.runtime.model.PuppetAtlas
import org.umamo.runtime.model.PuppetModel
import org.umamo.ui.viewport.AtlasPageBinding
import kotlin.test.Test
import kotlin.test.assertNull
import kotlin.test.assertSame
/**
* Pins the render loop's model/pages pairing: an atlas-changing model is held until the binding
* composed for its atlas arrives (undo must never render repacked pixels under baseline
* coordinates), non-atlas edits pass untouched, and the baseline's equal-but-distinct atlas
* instance still pairs. Pure - the decision is exactly what the loop carries out.
*/
class AtlasPairingTest {
private fun modelWith(atlas: PuppetAtlas): PuppetModel =
PuppetModel(
parameters = emptyList(),
parts = emptyList(),
deformers = emptyList(),
drawables = emptyList(),
rootChildren = emptyList(),
rootPartId = null,
canvasWidth = 10f,
canvasHeight = 10f,
worldOriginX = 5f,
worldOriginZ = 5f,
atlas = atlas,
)
private fun bindingFor(atlas: PuppetAtlas): AtlasPageBinding =
AtlasPageBinding(atlas, PuppetTextures(emptyList(), emptyMap(), premultipliedAlpha = false))
private val baselineAtlas = PuppetAtlas(pages = listOf(AtlasPage(64, 64)))
private val repackedAtlas = PuppetAtlas(pages = listOf(AtlasPage(128, 128)))
@Test
fun aNonAtlasEditPassesUntouched() {
val baseline = modelWith(baselineAtlas)
val applied = bindingFor(baselineAtlas)
val edited = baseline.copy(canvasWidth = 20f)
val decision = resolveAtlasPairing(edited, applied, applied, baseline)
assertSame(edited, decision.orderModel, "a same-atlas model renders immediately")
assertNull(decision.applyBinding, "and swaps nothing")
}
@Test
fun anAtlasChangingModelWaitsForItsPages() {
val baseline = modelWith(baselineAtlas)
val applied = bindingFor(baselineAtlas)
val repacked = modelWith(repackedAtlas)
val held = resolveAtlasPairing(repacked, applied, applied, baseline)
assertSame(baseline, held.orderModel, "the previous pair keeps rendering while pages are in flight")
assertNull(held.applyBinding)
val newBinding = bindingFor(repackedAtlas)
val released = resolveAtlasPairing(repacked, newBinding, applied, baseline)
assertSame(repacked, released.orderModel, "the matching binding releases the hold")
assertSame(newBinding, released.applyBinding, "and the pages swap first")
}
@Test
fun undoHoldsUntilTheBaselinePagesComeBack() {
val baseline = modelWith(baselineAtlas)
val repacked = modelWith(repackedAtlas)
val repackedBinding = bindingFor(repackedAtlas)
val held = resolveAtlasPairing(baseline, repackedBinding, repackedBinding, repacked)
assertSame(repacked, held.orderModel, "baseline coordinates must not render against repacked pixels")
assertNull(held.applyBinding)
val baselineBinding = bindingFor(baselineAtlas)
val released = resolveAtlasPairing(baseline, baselineBinding, repackedBinding, repacked)
assertSame(baseline, released.orderModel)
assertSame(baselineBinding, released.applyBinding)
}
@Test
fun anEqualButDistinctBaselineAtlasStillPairs() {
// The session's baseline short-circuit can publish the baseline pages under an atlas instance
// that is equal to - but not identical with - the model's own.
val modelAtlasTwin = PuppetAtlas(pages = listOf(AtlasPage(64, 64)))
val model = modelWith(modelAtlasTwin)
val applied = bindingFor(repackedAtlas)
val baselineBinding = bindingFor(baselineAtlas)
val decision = resolveAtlasPairing(model, baselineBinding, applied, modelWith(repackedAtlas))
assertSame(model, decision.orderModel, "structural equality is enough to pair")
assertSame(baselineBinding, decision.applyBinding)
}
@Test
fun aBindingRepublishUnderTheCurrentAtlasAppliesAlone() {
// The resolver's derive-failure fallback republishes pages under the model's own atlas.
val model = modelWith(repackedAtlas)
val applied = bindingFor(repackedAtlas)
val republished = bindingFor(repackedAtlas)
val decision = resolveAtlasPairing(model, republished, applied, model)
assertSame(model, decision.orderModel)
assertSame(republished, decision.applyBinding, "new pages under an unchanged atlas still swap")
}
@Test
fun theFirstTickRendersThePublishedModelRegardless() {
val model = modelWith(repackedAtlas)
val applied = bindingFor(baselineAtlas)
val decision = resolveAtlasPairing(model, applied, applied, lastModel = null)
assertSame(model, decision.orderModel, "with no previous pair there is nothing to hold")
assertNull(decision.applyBinding)
}
}
@@ -0,0 +1,195 @@
package org.umamo.editor.desktop.viewport
import androidx.compose.ui.graphics.toPixelMap
import org.umamo.render.DecodedImage
import org.umamo.render.PuppetTextures
import org.umamo.runtime.model.AtlasPage
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.KeyformAxis
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshDeltaForm
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PuppetAtlas
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.visibleDrawableIds
import org.umamo.ui.viewport.AtlasPageBinding
import org.umamo.ui.viewport.LiveParams
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* The live-repack integration gate, one level above the renderer: a real OffscreenPuppetService with
* its render thread and pairing loop, driven with the exact publish sequence the UI performs on a
* repack - setModel with a NEW atlas value, setAtlasPages with the binding composed for it - and
* then a plain UV edit. The UV edit is the point: after a page-count-changing repack, editing a
* mapping must still re-render (the modelG report: UV edits stopped updating the render after a
* 5-page document repacked to 2).
*
* Self-skips when no GL context can be created (no frame ever arrives).
*/
class AtlasSwapModelUpdateTest {
private val paramA = ParameterId("A")
private val probeId = DrawableId("SwapProbe")
// A 120x120 quad centered at the origin, keyed with one zero-delta form.
private val quadPositions = floatArrayOf(-60f, -60f, 60f, -60f, -60f, 60f, 60f, 60f)
private val quadIndices = intArrayOf(0, 1, 2, 1, 3, 2)
private fun quadUvs(centerU: Float, centerV: Float, halfSpan: Float = 0.2f): FloatArray =
floatArrayOf(
centerU - halfSpan,
centerV + halfSpan,
centerU + halfSpan,
centerV + halfSpan,
centerU - halfSpan,
centerV - halfSpan,
centerU + halfSpan,
centerV - halfSpan,
)
private fun solidImage(red: Int, green: Int, blue: Int, size: Int = 16): DecodedImage {
val rgba = ByteArray(size * size * 4)
for (pixel in rgba.indices step 4) {
rgba[pixel] = red.toByte()
rgba[pixel + 1] = green.toByte()
rgba[pixel + 2] = blue.toByte()
rgba[pixel + 3] = 0xFF.toByte()
}
return DecodedImage(rgba, size, size)
}
/** A 16x16 page whose left half is blue and right half is white. */
private fun blueWhiteImage(): DecodedImage {
val size = 16
val rgba = ByteArray(size * size * 4)
for (rowIndex in 0 until size) {
for (columnIndex in 0 until size) {
val pixel = (rowIndex * size + columnIndex) * 4
val white = columnIndex >= size / 2
rgba[pixel] = if (white) 0xFF.toByte() else 0x00
rgba[pixel + 1] = if (white) 0xFF.toByte() else 0x00
rgba[pixel + 2] = 0xFF.toByte()
rgba[pixel + 3] = 0xFF.toByte()
}
}
return DecodedImage(rgba, size, size)
}
private fun modelWith(atlas: PuppetAtlas, uvs: FloatArray): PuppetModel {
val drawable =
Drawable(
id = probeId,
name = "SwapProbe",
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(quadPositions.copyOf(), uvs, quadIndices),
geometryGrid =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0f))),
listOf(KeyformCell(intArrayOf(0), MeshDeltaForm(FloatArray(quadPositions.size)))),
),
)
return PuppetModel(
parameters = listOf(Parameter(paramA, "A", -1f, 1f, 0f)),
parts = emptyList(),
deformers = emptyList(),
drawables = listOf(drawable),
rootChildren = listOf(OrgChild.Drawable(drawable.id)),
rootPartId = null,
atlas = atlas,
)
}
/** Waits until the area publishes a frame satisfying [accept], or returns null on timeout. */
private fun awaitFrame(
frames: kotlinx.coroutines.flow.StateFlow<org.umamo.ui.viewport.RenderedFrame?>,
deadlineMillis: Long = 5_000,
accept: (androidx.compose.ui.graphics.PixelMap) -> Boolean,
): Boolean {
val start = System.currentTimeMillis()
while (System.currentTimeMillis() - start < deadlineMillis) {
val frame = frames.value
if (frame != null && accept(frame.bitmap.toPixelMap())) {
return true
}
Thread.sleep(20)
}
return false
}
private fun centerChannelDominates(pixels: androidx.compose.ui.graphics.PixelMap, channel: String): Boolean {
val color = pixels[pixels.width / 2, pixels.height / 2]
val red = color.red
val green = color.green
val blue = color.blue
return when (channel) {
"red" -> red > green + 0.25f && red > blue + 0.25f
"blue" -> blue > red + 0.25f && blue > green + 0.25f
"white" -> red > 0.7f && green > 0.7f && blue > 0.7f
else -> false
}
}
@Test
fun aUvEditAfterAPageCountChangingRepackStillRerenders() {
val baselineAtlas = PuppetAtlas(pages = listOf(AtlasPage(16, 16)))
val baselineModel = modelWith(baselineAtlas, quadUvs(0.5f, 0.5f))
val baselineTextures = PuppetTextures(listOf(solidImage(0xFF, 0x00, 0x00)), mapOf(probeId.raw to 0), false)
val service = OffscreenPuppetService(baselineModel, baselineTextures, LiveParams(emptyMap()))
service.start()
try {
val frames = service.register("area")
service.resize("area", 100, 100)
val sawBaseline = awaitFrame(frames) { pixels -> centerChannelDominates(pixels, "red") }
if (!sawBaseline) {
println("[atlas-swap-live] no GL frame arrived; skipping (context unavailable, or baseline never rendered)")
return
}
// The repack, in the UI's publish order: the committed model first (the session collector),
// then the binding composed for its atlas (the resolver). Page count changes 1 -> 2 and the
// probe moves to page 1, whose LEFT half is blue.
val repackedAtlas = PuppetAtlas(pages = listOf(AtlasPage(16, 16), AtlasPage(16, 16)))
val repackedModel = modelWith(repackedAtlas, quadUvs(0.25f, 0.5f))
val repackedTextures =
PuppetTextures(
listOf(solidImage(0x00, 0xFF, 0x00), blueWhiteImage()),
mapOf(probeId.raw to 1),
false,
)
service.setModel(repackedModel)
service.setShownDrawables(repackedModel.visibleDrawableIds())
service.setAtlasPages(AtlasPageBinding(repackedAtlas, repackedTextures))
assertTrue(
awaitFrame(frames) { pixels -> centerChannelDominates(pixels, "blue") },
"the repacked pair must render (probe on page 1's blue half)",
)
// The UV edit: same atlas instance, the mapping moves to the WHITE half. This is the exact
// gesture the modelG report says stops updating the render.
val editedModel =
repackedModel.copy(
drawables =
listOf(
repackedModel.drawables.single().let { drawable ->
drawable.copy(mesh = DrawableMesh(drawable.mesh!!.positions, quadUvs(0.75f, 0.5f), drawable.mesh!!.indices))
},
),
)
service.setModel(editedModel)
assertTrue(
awaitFrame(frames) { pixels -> centerChannelDominates(pixels, "white") },
"a UV edit after the repack must re-render (probe moved to page 1's white half)",
)
} finally {
service.dispose()
}
}
}
@@ -0,0 +1,361 @@
package org.umamo.editor.desktop.viewport
import org.umamo.render.ContentBounds
import org.umamo.render.DecodedImage
import org.umamo.render.ViewportCamera
import org.umamo.ui.viewport.AreaCameraKey
import org.umamo.ui.viewport.CameraSurface
import org.umamo.ui.viewport.UvSceneContent
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotEquals
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Pins how an area's scene routing is published, which decides what the render loop draws it as and
* which content bounds its camera fits.
*
* These are pure state assertions - no GL, no render thread - because the routing is pure state. The
* engine reads exactly these fields to choose between drawing the posed puppet and drawing a flat UV
* surface, so a slot that reads as the wrong kind sends an area to the wrong renderer and fits it to
* the wrong bounds, which shows up as artwork that is simply in the wrong place.
*/
class ViewportAreaRegistryTest {
private fun image(width: Int = 4, height: Int = 4): DecodedImage =
DecodedImage(ByteArray(width * height * 4), width, height)
/**
* A registered UV area reads as a UV scene, not as a puppet.
*
* The regression this exists for: the kind and the content were once published as separate fields,
* and collapsing them into one value dropped the kind write. Every UV area then still read as
* Puppet2D, so the engine fit each one to the PUPPET's rest bounds instead of the page rectangle and
* the atlas landed far off origin - while every existing test stayed green, because nothing covered
* this routing at all.
*/
@Test
fun registeringAUvSceneMarksTheAreaAsUv() {
val registry = ViewportAreaRegistry()
registry.registerUvScene("uv", UvSceneContent.AtlasPage(0), null)
val slot = registry.areas.getValue("uv")
assertEquals(RenderScene.UvScene, slot.scene, "a UV area must not read as a puppet area")
assertEquals(UvSceneContent.AtlasPage(0), slot.uvContent, "and it carries the content it registered with")
}
/** A puppet area stays a puppet area, and carries no UV surface. */
@Test
fun registeringAPuppetAreaLeavesItAPuppet() {
val registry = ViewportAreaRegistry()
registry.register("puppet")
val slot = registry.areas.getValue("puppet")
assertEquals(RenderScene.Puppet2D, slot.scene, "the puppet area keeps the puppet scene")
assertNull(slot.uvContent, "and has no UV surface to draw")
}
/**
* Retargeting a UV area replaces its whole surface, kind and payload together.
*
* A page and a layer are addressed differently - one by index into the document's uploaded pages,
* one by pixels the engine has never seen - so a switch that carried over half of the old choice
* would draw one surface while the freshness test spoke for the other.
*/
@Test
fun retargetingReplacesTheWholeSurface() {
val registry = ViewportAreaRegistry()
registry.registerUvScene("uv", UvSceneContent.AtlasPage(0), null)
val slot = registry.areas.getValue("uv")
val layer = image()
registry.setUvSceneContent("uv", UvSceneContent.SourceLayer("layer", layer), null)
assertEquals(UvSceneContent.SourceLayer("layer", layer), slot.uvContent, "the layer view replaces the page view whole")
assertEquals(RenderScene.UvScene, slot.scene, "and it is still a UV area")
registry.setUvSceneContent("uv", UvSceneContent.AtlasPage(2), null)
assertEquals(UvSceneContent.AtlasPage(2), slot.uvContent, "and switching back replaces it whole again")
}
/**
* Retargeting never turns a puppet area into a UV one.
*
* The puppet / UV split is fixed at registration; only the surface within the UV family moves.
*/
@Test
fun retargetingIgnoresAPuppetArea() {
val registry = ViewportAreaRegistry()
registry.register("puppet")
registry.setUvSceneContent("puppet", UvSceneContent.AtlasPage(1), null)
val slot = registry.areas.getValue("puppet")
assertEquals(RenderScene.Puppet2D, slot.scene, "a puppet area is not retargetable into a UV scene")
assertNull(slot.uvContent, "and takes on no UV surface")
}
/** An unregistered area is a no-op rather than a crash, since requests can outlive their area. */
@Test
fun retargetingAnUnknownAreaDoesNothing() {
val registry = ViewportAreaRegistry()
registry.setUvSceneContent("gone", UvSceneContent.AtlasPage(0), null)
assertTrue(registry.areas.isEmpty(), "no slot is conjured for an area that never registered")
}
/**
* A UV area survives the register-before-unregister overlap a tree collapse produces.
*
* Closing a split sibling rebuilds the surviving area's leaf under a fresh composition node, so the
* new register runs BEFORE the old unregister. The slot must still be a UV area afterwards.
*/
@Test
fun aReRegisteredUvAreaSurvivesTheOverlap() {
val registry = ViewportAreaRegistry()
registry.registerUvScene("uv", UvSceneContent.AtlasPage(0), null)
registry.registerUvScene("uv", UvSceneContent.AtlasPage(1), null)
registry.unregister("uv")
val slot = registry.areas.getValue("uv")
assertEquals(RenderScene.UvScene, slot.scene, "the surviving hold keeps the area a UV scene")
assertEquals(UvSceneContent.AtlasPage(1), slot.uvContent, "with the content the rebuilt leaf registered")
}
/**
* Switching an area's editor type in place - the UV editor to the 2D viewport - hands the slot to the new space.
*
* The new space registers BEFORE the old one releases (it composes first), so the slot never drops to zero and
* is reused as it stands: still a UV scene, still holding the page, still on the page's camera. Left that way
* the engine keeps drawing the atlas page under the 2D viewport's gizmos, framed by a pan and zoom that mean
* nothing in the puppet's world. A registration claims all three.
*/
@Test
fun switchingAUvEditorToAViewportInPlaceRetargetsTheSlot() {
val registry = ViewportAreaRegistry()
val pageBounds = ContentBounds(0f, 0f, 4096f, 4096f)
val puppetBounds = ContentBounds(-600f, -900f, 1200f, 1800f)
registry.registerUvScene("area", UvSceneContent.AtlasPage(0), null)
val slot = registry.areas.getValue("area")
val pageCamera = registry.establishCamera(slot, "area", 800, 600) { _, _ -> pageBounds }
// The space switch: the viewport registers while the UV editor still holds the area, then the editor lets go.
registry.register("area")
registry.unregister("area")
assertEquals(slot, registry.areas["area"], "the slot survives the switch - the area never went unheld")
assertEquals(RenderScene.Puppet2D, slot.scene, "and now reads as a puppet area")
assertNull(slot.uvContent, "with no UV surface left to draw")
assertNull(slot.camera, "and no camera, so the engine establishes the puppet's view")
assertNull(slot.imageState.value, "and no last frame of the page to show under the viewport's overlays")
val puppetCamera = registry.establishCamera(slot, "area", 800, 600) { _, _ -> puppetBounds }
assertEquals(ViewportCamera.fit(puppetBounds, 800, 600), puppetCamera, "the puppet is fitted, not framed by the page's camera")
// And back: each surface kept its own view for the area.
registry.registerUvScene("area", UvSceneContent.AtlasPage(0), null)
registry.unregister("area")
assertEquals(RenderScene.UvScene, slot.scene)
assertEquals(pageCamera, registry.establishCamera(slot, "area", 800, 600) { _, _ -> error("the page's view is remembered, not refitted") })
}
/**
* A leaf rebuilt for the SAME space - a tree collapse registers the survivor again before its old leaf releases -
* keeps its camera and its frame: only a change of kind is a claim.
*/
@Test
fun reRegisteringTheSameSpaceKeepsTheView() {
val registry = ViewportAreaRegistry()
registry.register("area")
val slot = registry.areas.getValue("area")
val camera = registry.establishCamera(slot, "area", 800, 600) { _, _ -> ContentBounds(0f, -100f, 100f, 100f) }
registry.register("area")
registry.unregister("area")
assertEquals(camera, slot.camera)
assertEquals(camera, slot.cameraState.value)
}
/**
* A camera seeded before an area registers is the one the area opens on, in place of a fit - how a saved
* document reopens each area on the view it was left with (docs/format/UMA.md § 7.3). A seed is for one
* surface: the same area showing the other surface fits instead.
*/
@Test
fun aSeededCameraIsWhatTheAreaOpensOn() {
val registry = ViewportAreaRegistry()
val saved = ViewportCamera(120f, -340f, 2.5f)
registry.seedCameras(
mapOf(
AreaCameraKey("viewport", CameraSurface.Viewport) to saved,
AreaCameraKey("never-shown", CameraSurface.Viewport) to ViewportCamera(1f, 1f, 1f),
AreaCameraKey("now-a-uv-editor", CameraSurface.Viewport) to ViewportCamera(2f, 2f, 2f),
),
)
registry.register("viewport")
registry.register("fresh")
registry.registerUvScene("now-a-uv-editor", UvSceneContent.AtlasPage(0), null)
val fitBounds = ContentBounds(0f, -100f, 100f, 100f)
val restored = registry.establishCamera(registry.areas.getValue("viewport"), "viewport", 800, 600) { _, _ -> error("a seeded area must not fit") }
val fitted = registry.establishCamera(registry.areas.getValue("fresh"), "fresh", 800, 600) { _, _ -> fitBounds }
val otherSurface = registry.establishCamera(registry.areas.getValue("now-a-uv-editor"), "now-a-uv-editor", 800, 600) { _, _ -> fitBounds }
assertEquals(saved, restored)
assertEquals(ViewportCamera.fit(fitBounds, 800, 600), fitted, "an area with nothing saved fits its content, as before")
assertEquals(ViewportCamera.fit(fitBounds, 800, 600), otherSurface, "a view saved for the puppet is not applied to a texture")
assertEquals(ViewportCamera(2f, 2f, 2f), registry.cameras()[AreaCameraKey("now-a-uv-editor", CameraSurface.Viewport)], "and stays remembered for the day the area shows a viewport again")
assertTrue(AreaCameraKey("never-shown", CameraSurface.Viewport) in registry.cameras(), "every remembered camera is readable for the next save")
}
/** Seeding never moves an area that already has a camera: it is for the moment the engine is built. */
@Test
fun seedingLeavesAnEstablishedCameraAlone() {
val registry = ViewportAreaRegistry()
registry.register("viewport")
val established = registry.establishCamera(registry.areas.getValue("viewport"), "viewport", 800, 600) { _, _ -> ContentBounds(0f, -100f, 100f, 100f) }
registry.seedCameras(mapOf(AreaCameraKey("viewport", CameraSurface.Viewport) to ViewportCamera(9f, 9f, 9f)))
assertEquals(established, registry.cameras()[AreaCameraKey("viewport", CameraSurface.Viewport)])
}
/**
* A UV editor keeps a view per page and layer. Switching to one it has never shown fits that surface rather
* than carrying the page's pan and zoom over it - a layer a fraction of the page's size would land tiny and in a
* corner - and switching back brings back the view the first one was left with.
*/
@Test
fun eachSurfaceKeepsItsOwnView() {
val registry = ViewportAreaRegistry()
val pageBounds = ContentBounds(0f, 0f, 4096f, 4096f)
val layerBounds = ContentBounds(0f, 0f, 300f, 200f)
registry.registerUvScene("uv", UvSceneContent.AtlasPage(0), null)
val slot = registry.areas.getValue("uv")
registry.establishCamera(slot, "uv", 800, 600) { _, _ -> pageBounds }
registry.pan("uv", 40f, -25f)
val pannedPage = slot.camera
val layerContent = UvSceneContent.SourceLayer("layer-1", image(300, 200))
registry.setUvSceneContent("uv", layerContent, null)
assertEquals(pannedPage, slot.camera, "a retarget moves no camera by itself - the render thread swaps it with the next frame")
val layerView =
registry.establishCamera(slot, "uv", 800, 600) { _, content ->
assertEquals(layerContent, content, "the fit is of the content the swap files the view under")
layerBounds
}
assertEquals(ViewportCamera.fit(layerBounds, 800, 600), layerView, "a layer the area has never shown is fitted")
registry.setUvSceneContent("uv", UvSceneContent.AtlasPage(0), null)
assertEquals(pannedPage, registry.establishCamera(slot, "uv", 800, 600) { _, _ -> error("the page's view is remembered, not refitted") })
registry.setUvSceneContent("uv", UvSceneContent.SourceLayer("layer-1", image(300, 200)), null)
assertEquals(layerView, registry.establishCamera(slot, "uv", 800, 600) { _, _ -> error("a layer is known by its key, not its pixels") })
}
/** Two UV editors keep their own views: one's view of a page is not what the other opens that page on. */
@Test
fun twoAreasKeepSeparateViewsOfOnePage() {
val registry = ViewportAreaRegistry()
val pageBounds = ContentBounds(0f, 0f, 1024f, 1024f)
registry.registerUvScene("top", UvSceneContent.AtlasPage(1), null)
registry.registerUvScene("bottom", UvSceneContent.AtlasPage(0), null)
val top = registry.areas.getValue("top")
val bottom = registry.areas.getValue("bottom")
registry.establishCamera(top, "top", 800, 300) { _, _ -> pageBounds }
registry.zoomCentered("top", zoomIn = true, coarse = true)
registry.establishCamera(bottom, "bottom", 800, 300) { _, _ -> pageBounds }
registry.setUvSceneContent("bottom", UvSceneContent.AtlasPage(1), null)
assertEquals(ViewportCamera.fit(pageBounds, 800, 300), registry.establishCamera(bottom, "bottom", 800, 300) { _, _ -> pageBounds })
assertNotEquals(top.camera, bottom.camera, "and the top area's zoom stays its own")
}
/**
* An area put away by a workspace tab switch and brought back showing another surface - its selection moved
* while it was away - opens on that surface's view, or a fit, never on the last view it had of the old one.
*/
@Test
fun aReturningAreaOnAnotherSurfaceTakesThatSurfacesView() {
val registry = ViewportAreaRegistry()
val pageBounds = ContentBounds(0f, 0f, 2048f, 2048f)
registry.registerUvScene("uv", UvSceneContent.AtlasPage(0), null)
registry.establishCamera(registry.areas.getValue("uv"), "uv", 800, 600) { _, _ -> pageBounds }
registry.setUvSceneContent("uv", UvSceneContent.AtlasPage(1), null)
registry.establishCamera(registry.areas.getValue("uv"), "uv", 800, 600) { _, _ -> pageBounds }
registry.zoomCentered("uv", zoomIn = true, coarse = true)
val secondPageView = registry.areas.getValue("uv").camera
registry.setUvSceneContent("uv", UvSceneContent.AtlasPage(0), null)
registry.establishCamera(registry.areas.getValue("uv"), "uv", 800, 600) { _, _ -> error("the first page's view is remembered") }
registry.pan("uv", 120f, 0f)
// The tab switch drops the slot; the area comes back following a selection now on the second page.
registry.unregister("uv")
assertNull(registry.areas["uv"], "the slot is gone while its workspace is away")
registry.registerUvScene("uv", UvSceneContent.AtlasPage(1), null)
val returned = registry.establishCamera(registry.areas.getValue("uv"), "uv", 800, 600) { _, _ -> error("the second page's view is remembered") }
assertEquals(secondPageView, returned)
assertEquals(secondPageView, registry.cameras()[AreaCameraKey("uv", CameraSurface.Uv)], "and it is the view a save now writes")
registry.unregister("uv")
registry.registerUvScene("uv", UvSceneContent.SourceLayer("never-shown", image(64, 64)), null)
val layerBounds = ContentBounds(0f, 0f, 64f, 64f)
assertEquals(ViewportCamera.fit(layerBounds, 800, 600), registry.establishCamera(registry.areas.getValue("uv"), "uv", 800, 600) { _, _ -> layerBounds })
}
/**
* A saved document's UV view belongs to the surface the area opens on. Once the area has shown a surface this
* session, a surface it has not shown fits instead of inheriting the saved view.
*/
@Test
fun aSeededUvViewBelongsToTheFirstSurfaceShown() {
val registry = ViewportAreaRegistry()
val saved = ViewportCamera(300f, 200f, 0.5f)
val pageBounds = ContentBounds(0f, 0f, 1024f, 1024f)
registry.seedCameras(mapOf(AreaCameraKey("uv", CameraSurface.Uv) to saved))
registry.registerUvScene("uv", UvSceneContent.AtlasPage(3), null)
val slot = registry.areas.getValue("uv")
assertEquals(saved, registry.establishCamera(slot, "uv", 800, 600) { _, _ -> error("the saved view is what the area opens on") })
registry.setUvSceneContent("uv", UvSceneContent.AtlasPage(0), null)
assertEquals(ViewportCamera.fit(pageBounds, 800, 600), registry.establishCamera(slot, "uv", 800, 600) { _, _ -> pageBounds })
registry.setUvSceneContent("uv", UvSceneContent.AtlasPage(3), null)
assertEquals(saved, registry.establishCamera(slot, "uv", 800, 600) { _, _ -> error("and the opening page keeps it") })
}
/** A save sees one UV view per area, the shown surface's: the views kept for the other surfaces are session state. */
@Test
fun aSaveSeesOnlyTheShownSurfacesView() {
val registry = ViewportAreaRegistry()
val layerBounds = ContentBounds(0f, 0f, 300f, 200f)
registry.registerUvScene("uv", UvSceneContent.AtlasPage(0), null)
val slot = registry.areas.getValue("uv")
registry.establishCamera(slot, "uv", 800, 600) { _, _ -> ContentBounds(0f, 0f, 4096f, 4096f) }
registry.pan("uv", 10f, 10f)
registry.setUvSceneContent("uv", UvSceneContent.SourceLayer("layer-1", image(300, 200)), null)
val layerView = registry.establishCamera(slot, "uv", 800, 600) { _, _ -> layerBounds }
assertEquals(mapOf(AreaCameraKey("uv", CameraSurface.Uv) to layerView), registry.cameras())
}
/**
* A UV editor's fit frames the page, widened to every shown mesh that reaches past it: a placement moved off the
* page carries its islands with it, and a fit of the page alone would frame everything but what was just moved.
*/
@Test
fun aFitTakesInMeshesPastThePageEdge() {
val pageBounds = ContentBounds(0f, 0f, 1024f, 1024f)
val spilled = ContentBounds(900f, -300f, 600f, 400f)
val widened = ContentBounds(0f, -300f, 1500f, 1324f)
assertEquals(widened, uvFitBounds(pageBounds, spilled))
assertEquals(pageBounds, uvFitBounds(pageBounds, ContentBounds(10f, 10f, 20f, 20f)), "meshes inside the page leave the page fit alone")
assertEquals(pageBounds, uvFitBounds(pageBounds, null), "as does a surface with no meshes")
val registry = ViewportAreaRegistry()
registry.registerUvScene("uv", UvSceneContent.AtlasPage(0), spilled)
val slot = registry.areas.getValue("uv")
assertEquals(ViewportCamera.fit(widened, 800, 600), registry.establishCamera(slot, "uv", 800, 600) { _, _ -> pageBounds }, "the first fit takes the spill in")
registry.setUvSceneContent("uv", UvSceneContent.AtlasPage(0), ContentBounds(10f, 10f, 20f, 20f))
registry.fit("uv")
assertEquals(ViewportCamera.fit(pageBounds, 800, 600), registry.establishCamera(slot, "uv", 800, 600) { _, _ -> pageBounds }, "and Fit View follows the meshes back inside")
}
}