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
+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")
}
}