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
+123
View File
@@ -0,0 +1,123 @@
// :render — deformation eval (CPU) + the backend-neutral PuppetRenderer + morph-blend shaders, over a
// RenderDevice backend seam. Everything except the device impls is commonMain (jvm/android/iosArm64);
// GlRenderDevice (LWJGL, desktop GL 3.3) lives in jvmMain, the GLES/Metal devices are stubs in
// androidMain/iosMain. Zero expect/actual. Depends on :runtime for the puppet model.
// :render — 変形評価(CPU)+バックエンド非依存の PuppetRenderer。RenderDevice が継ぎ目で、GL 実装のみ
// jvmMain。GLES / Metal デバイスはスタブ。:runtime に依存。
plugins {
alias(libs.plugins.kotlinMultiplatform)
alias(libs.plugins.androidKmpLibrary)
// Umamo's own conventions (gradle/build-logic): the iosArm64 → `check` wiring, and the corpus/-D
// forwarding configured by `umamoTestCorpus` below. Deliberately NOT umamo.kmp-jvmandroid — this
// module has no JVM-bound shared code; see the commonMain :format comment below.
id("umamo.kmp-ios-gate")
id("umamo.test-corpus")
}
// EN: LWJGL ships its native libraries as classifier'd artifacts; pick the one for the build target.
// Default is the host; -Pumamo.target=<os>-<arch> cross-resolves (e.g. windows-x64 from WSL2). The
// selection is shared with :desktop so a cross-build can't bundle this module's host natives by
// mistake — see gradle/build-target.gradle.kts. (Desktop only — Android uses GLES via android.opengl.)
// JA: LWJGL のネイティブ分類子を選ぶ。既定はホスト、-Pumamo.target で他プラットフォーム向けに解決。
apply(from = rootProject.file("gradle/build-target.gradle.kts"))
val lwjglNatives = extra["umamoLwjglNatives"] as String
kotlin {
jvmToolchain(21)
// (The -Xexpect-actual-classes opt-in that used to sit here left with its only user, the
// `expect class GpuRenderer` — this module is zero expect/actual now; the backend seam is the
// RenderDevice interface instead.)
jvm()
// The iPadOS ship target, mirroring :format/:runtime (see :format's docblock for the rationale).
// This is what the Metal engineer builds against: iosMain sees the whole backend-neutral stack —
// PuppetRenderer, the RenderDevice API, eval, pose/diff/glue planning — and supplies one
// MetalRenderDevice. It also turns commonMain purity for all of that from the root regex gate's
// convention into a compiler guarantee. Compiles on Linux/CI (klib only, no Xcode linker); a device
// target has no runnable test task, so `umamo.kmp-ios-gate` wires `check` to the compiles.
iosArm64()
android {
namespace = "org.umamo.render"
compileSdk = libs.versions.android.compileSdk.get().toInt()
minSdk = libs.versions.android.minSdk.get().toInt()
}
sourceSets {
commonMain {
dependencies {
// `api` (not `implementation`): the deformation eval's public surface returns/accepts
// :runtime model types (PuppetModel, DrawableId, …), so consumers see them transitively.
api(project(":runtime"))
// `api`: :format types sit in the renderer's own public surface too — RasterImage in
// RenderDevice's upload API, PngCodec behind the atlas decode, and the CMO3/MOC3 node
// types the two texture adapters walk — and :runtime is format-free, so nothing supplies
// :format transitively. Those adapters are commonMain: the CMO3 graph node types live in
// :format's commonMain, and only the JDOM-built Cmo3Model wrapper does not, so the
// adapter takes a CModelSource plus an injected pixel lookup and this module needs no
// jvmAndroidMain at all.
api(project(":format"))
}
}
jvmMain {
dependencies {
// BOM aligns every LWJGL module to one version; the `::classifier` (empty
// version) coordinate inherits that version while adding the host natives.
implementation(project.dependencies.platform(libs.lwjgl.bom))
implementation(libs.lwjgl.core)
implementation(libs.lwjgl.opengl)
runtimeOnly("org.lwjgl:lwjgl::$lwjglNatives")
runtimeOnly("org.lwjgl:lwjgl-opengl::$lwjglNatives")
}
}
commonTest {
dependencies {
implementation(kotlin("test"))
}
}
jvmTest {
dependencies {
// The oracle/parity tests ingest corpus models through :interop's Cmo3Import/Moc3Import.
implementation(project(":interop"))
// Headless GL (GLFW hidden window) for the GPU-vs-CPU transform-feedback validation test.
// `implementation` here (not inherited from jvmMain's `implementation`) so the test sources
// compile against the GL/GLFW bindings; natives are pulled for the host.
implementation(project.dependencies.platform(libs.lwjgl.bom))
implementation(libs.lwjgl.core)
implementation(libs.lwjgl.opengl)
implementation(libs.lwjgl.glfw)
runtimeOnly("org.lwjgl:lwjgl::$lwjglNatives")
runtimeOnly("org.lwjgl:lwjgl-opengl::$lwjglNatives")
runtimeOnly("org.lwjgl:lwjgl-glfw::$lwjglNatives")
}
}
}
}
// Corpus + differential-oracle paths for the eval's gated tests (the `umamo.test-corpus` convention
// plugin): `./gradlew :render:jvmTest -Dcmo3.sample=… -Dmoc3.sample=… -Drelive.dumpModel=…
// -Drelive.coreLib=…`.
//
// `cmo3.sample`, `cmo3.probe`, and `moc3.samples` carry corpus DEFAULTS (see
// org.umamo.buildlogic.sharedCorpusDefault). Without them this module's corpus gates — the GPU-vs-CPU
// deform oracle above all — only ran when someone remembered the flag, so in practice they never ran:
// GpuDeformValidationTest, GlueCorpusTest, and RenderOrderCorpusTest all sat skipping on a machine that
// had the corpus the whole time. The deform oracle is the only pin on DEFORM_GLSL's math and the thing
// a Metal port will check itself against, so "runs only if asked" was the wrong default for it. The
// relive.* oracle paths and moc3.sample stay explicit-only.
//
// Absent entirely (a fresh clone, CI) → the tests skip and the build stays green, since test/corpus is
// gitignored on purpose (see README). That is deliberate; CI passes no sample flags.
//
// `umamo.requireGl` is forwarded for the opposite reason: it turns the GL tests' missing-context skip
// into a hard failure (see HeadlessGlGate). CI sets it so the GL suite can never silently stop covering
// anything; a developer machine leaves it unset and gets the skip. It is a flag, not a path, so it goes
// through `flag` and skips the file-existence check.
umamoTestCorpus {
maxHeap("4g")
sample("cmo3.sample", "cmo3.probe", "moc3.sample", "moc3.samples", "relive.dumpModel", "relive.coreLib")
flag("umamo.requireGl")
}
@@ -0,0 +1,134 @@
package org.umamo.render.gles
import org.umamo.format.raster.RasterImage
import org.umamo.render.device.DeformCapturePipeline
import org.umamo.render.device.DeformedPositionStore
import org.umamo.render.device.FrameEncoder
import org.umamo.render.device.GpuMesh
import org.umamo.render.device.GpuTexture
import org.umamo.render.device.MeshSpec
import org.umamo.render.device.ReadbackTicket
import org.umamo.render.device.RenderDevice
import org.umamo.render.device.RenderPipeline
import org.umamo.render.device.RenderPipelineSpec
import org.umamo.render.device.RenderTarget
import org.umamo.render.device.RenderTargetSpec
import org.umamo.render.device.ScissorRect
import org.umamo.render.device.TextureFilter
import org.umamo.render.device.TextureFormat
import org.umamo.render.device.TextureWrap
/**
* The Android GLES 3.0 [RenderDevice] - a STUB marking the port's entry point; nothing is implemented.
*
* The port is a near-transliteration of the desktop `GlRenderDevice` (jvmMain, `org.umamo.render.gl`):
* the calls are the same, the shared GLSL comes from `org.umamo.render.glsl` with
* `GlslDialect.Es300`, and `PuppetRenderer` needs no changes at all. The mechanical difference is
* binding style - LWJGL statics returning values vs `android.opengl.GLES30`'s out-parameter form
* (`glGenTextures(1, ids, 0)` instead of `glGenTextures()`).
*
* The ONE real divergence is [createDeformedPositionStore]. The desktop device backs the glue store
* with a texture buffer object, and TBOs are GLES 3.2 - the baseline here is 3.0. The 3.0-clean
* route (TODO.md Claude Note § Android GLES renderer backend, option (b)):
* - Store: a regular RG32F 2D texture, indexed `(index % width, index / width)` via texelFetch.
* - Capture: transform feedback IS core in ES 3.0 but can only target a buffer, so pass 1 becomes
* TF into a buffer, then buffer → texture via a GL_PIXEL_UNPACK_BUFFER bind + glTexSubImage2D
* (both core 3.0). Do NOT reach for the point-scatter alternative here: rendering INTO an RG32F
* target needs EXT_color_buffer_float, which is not core until 3.2 either.
* - Shader: `glueVertexShader(Es300)` still emits `samplerBuffer` and must gain the 2D-texelFetch
* variant as part of this port - its `@warning` says so.
*
* Everything else - pipelines keyed by `PipelinePurpose`, the pass encoders, `barrier` as glFinish,
* `readPixels` flipping GL's bottom-up read to the API's top-first contract - carries over as is.
* Validate against the same oracles the desktop device passes: `GpuDeformValidationTest` and
* `GpuGlueValidationTest` are the correctness bar, run on-device or on an emulator.
*
* Android GLES 3.0 デバイスのスタブ。デスクトップ GL デバイスの移植入口。未実装。
*/
class GlesRenderDevice : RenderDevice {
override fun createTexture(
width: Int,
height: Int,
format: TextureFormat,
filter: TextureFilter,
pixels: ByteArray?,
wrap: TextureWrap,
): GpuTexture =
TODO("GLES port: transliterate GlRenderDevice.createTexture (GLES30.glGenTextures out-param form)")
override fun createFloatTexture(width: Int, height: Int, filter: TextureFilter, texels: FloatArray): GpuTexture =
TODO("GLES port: transliterate GlRenderDevice.createFloatTexture")
override fun updateFloatTexture(texture: GpuTexture, width: Int, height: Int, texels: FloatArray): Unit =
TODO("GLES port: transliterate GlRenderDevice.updateFloatTexture (keep the once-per-pose contract)")
override fun createMesh(spec: MeshSpec): GpuMesh = TODO("GLES port: transliterate GlRenderDevice.createMesh")
override fun updateMeshPositions(mesh: GpuMesh, restPositions: FloatArray): Unit =
TODO("GLES port: transliterate GlRenderDevice.updateMeshPositions")
override fun updateMeshUvs(mesh: GpuMesh, uvs: FloatArray): Unit = TODO("GLES port: transliterate GlRenderDevice.updateMeshUvs")
override fun createRenderTarget(spec: RenderTargetSpec): RenderTarget =
TODO("GLES port: transliterate GlRenderDevice.createRenderTarget")
override fun createDeformedPositionStore(vertexCapacity: Int): DeformedPositionStore =
TODO("GLES port: THE divergence - RG32F 2D texture store + TF-to-buffer + PBO copy; see the class docblock")
override fun createRenderPipeline(spec: RenderPipelineSpec): RenderPipeline =
TODO("GLES port: link from org.umamo.render.glsl with GlslDialect.Es300")
override fun createDeformCapturePipeline(): DeformCapturePipeline =
TODO("GLES port: TF program (core in ES 3.0), capture into the store's staging buffer")
override fun destroyTexture(texture: GpuTexture): Unit = TODO("GLES port")
override fun destroyMesh(mesh: GpuMesh): Unit = TODO("GLES port")
override fun destroyRenderTarget(target: RenderTarget): Unit = TODO("GLES port")
override fun beginFrame(): FrameEncoder = TODO("GLES port: transliterate GlFrameEncoder")
override fun resolve(source: RenderTarget, destination: RenderTarget, region: ScissorRect?): Unit =
TODO(
"GLES port: two branches like desktop GlRenderDevice - region == null is the full-surface " +
"GL_LINEAR downscale blit (the supersample resolve); region != null is a same-size, top-left-" +
"origin sub-rect GL_NEAREST copy (the composite snapshot). glBlitFramebuffer is core in ES 3.0.",
)
override fun resolveUsed(
source: RenderTarget,
sourceUsedWidth: Int,
sourceUsedHeight: Int,
destination: RenderTarget,
destinationUsedWidth: Int,
destinationUsedHeight: Int,
region: ScissorRect?,
): Unit =
TODO(
"GLES port: like resolve but over the bottom-left used regions (passes viewport at the " +
"origin), flipping a non-null region against the USED height - see desktop GlRenderDevice.",
)
override fun beginReadback(target: RenderTarget): ReadbackTicket =
TODO("GLES port: PBO + fence, same as desktop - GL_PIXEL_PACK_BUFFER and fence sync are core in ES 3.0")
override fun beginReadback(target: RenderTarget, usedWidth: Int, usedHeight: Int): ReadbackTicket =
TODO("GLES port: the full-target beginReadback with glReadPixels(0, 0, usedWidth, usedHeight, ...)")
override fun pollReadback(ticket: ReadbackTicket): RasterImage? =
TODO("GLES port: clientWaitSync(0) + glMapBufferRange (ES has no glMapBuffer; use the Range form)")
override fun cancelReadback(ticket: ReadbackTicket): Unit = TODO("GLES port")
override fun readPixels(target: RenderTarget): RasterImage =
TODO("GLES port: glReadPixels + flipRowsVertically - GLES reads bottom-up like GL; the API contract is top-first")
override fun readPixels(target: RenderTarget, usedWidth: Int, usedHeight: Int): RasterImage =
TODO("GLES port: the full-target readPixels with glReadPixels(0, 0, usedWidth, usedHeight, ...)")
override fun maxRenderTargetSize(): Int =
TODO("GLES port: the least of GL_MAX_TEXTURE_SIZE, GL_MAX_RENDERBUFFER_SIZE, and both GL_MAX_VIEWPORT_DIMS")
override fun describeBackend(): String = TODO("GLES port: GLES20.glGetString(GL_RENDERER / GL_VERSION / GL_VENDOR)")
}
@@ -0,0 +1,658 @@
package org.umamo.render
import org.umamo.format.art.LayerBounds
import org.umamo.format.atlas.AtlasPackReserve
import org.umamo.runtime.model.AtlasPlacement
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.applyUvAffine
import org.umamo.runtime.model.inversePlacementAffine
import org.umamo.runtime.model.placementAffine
import org.umamo.runtime.model.storedToArtAffineForTile
import kotlin.math.ceil
import kotlin.math.floor
/*
* The placement gizmo's page-space bookkeeping: the mesh reach each tile must keep clear, the
* footprint a placement occupies on its page, and the two regions a collision is made of.
*
* A collision is asymmetric and exact on both sides. What goes wrong when tiles overlap is a mesh
* SAMPLING another tile's opaque pixels, so every tile has a sampled region - the coverage of its
* triangles, rasterized in its own pixel frame, through its placement - and a painted region - its
* opaque texels, the composer never letting a transparent one erase anything - and tile A collides
* with tile B when A's triangles land on B's paint or B's triangles land on A's paint. The two sides
* are different shapes on purpose: the typical mesh extends PAST its art, and those overhanging
* triangles are exactly where a neighbor's pixels cause damage, while a tile's pixels outside its own
* mesh are still paint another tile's triangles can land on. A bounding box on either side lies for
* strand-shaped art and for meshes that sample only part of their layer. A mover's paint is its own
* opaque mask; the bystanders' paint is the shown page itself, whose composed alpha IS what is painted
* there.
*
* Session-free and GL-free. It lives beside the derivation rather than in the editing module because
* a footprint is a derivation question (which pixels will the compose write) and needs the trim the
* derivation draws, and because the repack and the drag must reserve by ONE rule - a reserve computed
* two ways would let a hand-nudged tile land where the next repack refuses to put it.
*/
/**
* Per tile, the union of its bound drawables' mesh reach in the tile's own art frame, rounded out to
* whole pixels - what a pack must keep clear BEYOND the opaque pixels.
*
* The pixels alone do not bound what samples a tile: an art mesh rings outside the opaque region
* (Erica's reach up to 58px past their trim, and past the raster itself), so a pack spaced by
* opaque bounds puts one tile's mesh footprint over its neighbor's art - the mesh then renders the
* neighbor's pixels wherever they are opaque. The official editor's own packing keeps mesh
* footprints disjoint, and this is how the repack matches it.
*
* A drawable whose mapping will not resolve (a placement naming a page the atlas lacks) contributes
* nothing here; if it is bound, the repack's refusal pass aborts before the reserve could have
* mattered.
*
* @param PuppetModel model The model whose bindings to measure.
* @return Map Each bound tile's reserve, absent when a tile has no measurable mesh.
*/
public fun meshReserveByTile(model: PuppetModel): Map<AtlasTileId, AtlasPackReserve> {
val boundsByTile = HashMap<AtlasTileId, FloatArray>()
for (drawable in model.drawables) {
val tileId = drawable.atlasTileId ?: continue
val tile = model.atlas.tileById[tileId] ?: continue
val uvs = drawable.mesh?.uvs ?: continue
if (uvs.size < 2) {
continue
}
val storedToArt = model.atlas.storedToArtAffineForTile(tileId) ?: continue
val artUvs = applyUvAffine(uvs, storedToArt)
val bounds = boundsByTile.getOrPut(tileId) { floatArrayOf(Float.MAX_VALUE, Float.MAX_VALUE, -Float.MAX_VALUE, -Float.MAX_VALUE) }
var componentIndex = 0
while (componentIndex + 1 < artUvs.size) {
val artX = artUvs[componentIndex] * tile.width
val artY = artUvs[componentIndex + 1] * tile.height
bounds[0] = minOf(bounds[0], artX)
bounds[1] = minOf(bounds[1], artY)
bounds[2] = maxOf(bounds[2], artX)
bounds[3] = maxOf(bounds[3], artY)
componentIndex += 2
}
}
return boundsByTile.mapValues { (_, bounds) ->
AtlasPackReserve(
left = floor(bounds[0]).toInt(),
top = floor(bounds[1]).toInt(),
right = ceil(bounds[2]).toInt(),
bottom = ceil(bounds[3]).toInt(),
)
}
}
/**
* A placement's axis-aligned extent on its page, in continuous page pixels: the bounds of the
* tile-local rectangle (the trim, widened by the mesh reserve) through the placement.
*
* A rotated tile's footprint is its bounding box, so a test over one over-warns for a turned tile and
* never under-warns - the first-cut approximation the gizmo's warnings run on.
*
* @property Float left The left edge.
* @property Float top The top edge.
* @property Float right The right edge, exclusive.
* @property Float bottom The bottom edge, exclusive.
*/
data class PlacementFootprint(
val left: Float,
val top: Float,
val right: Float,
val bottom: Float,
) {
/**
* This footprint grown by [margin] on every side - the gutter a neighbor must stay clear of.
*
* @param Float margin The growth in page pixels.
* @return PlacementFootprint The grown footprint.
*/
fun expanded(margin: Float): PlacementFootprint = PlacementFootprint(left - margin, top - margin, right + margin, bottom + margin)
/**
* True when this footprint and [other] share any area (touching edges do not count).
*
* @param PlacementFootprint other The footprint to test against.
* @return Boolean Whether they overlap.
*/
fun overlaps(other: PlacementFootprint): Boolean =
left < other.right && other.left < right && top < other.bottom && other.top < bottom
/**
* True when any part of this footprint lies outside a page of the given size.
*
* @param Int pageWidth The page width in pixels.
* @param Int pageHeight The page height in pixels.
* @return Boolean Whether the footprint spills off the page.
*/
fun exceeds(pageWidth: Int, pageHeight: Int): Boolean = left < 0f || top < 0f || right > pageWidth || bottom > pageHeight
}
/**
* The footprint [placement] occupies: its tile's [trim] widened by [reserve] (when the tile has a
* measurable mesh), carried through the placement onto the page.
*
* @param AtlasPlacement placement The tile's placement.
* @param LayerBounds trim The tile's opaque bounds, raster-local.
* @param AtlasPackReserve? reserve The tile's mesh reach, raster-local, or null when none.
* @return PlacementFootprint The page-space bounds.
*/
fun placementFootprint(placement: AtlasPlacement, trim: LayerBounds, reserve: AtlasPackReserve?): PlacementFootprint {
var localLeft = trim.left.toFloat()
var localTop = trim.top.toFloat()
var localRight = (trim.left + trim.width).toFloat()
var localBottom = (trim.top + trim.height).toFloat()
if (reserve != null) {
localLeft = minOf(localLeft, reserve.left.toFloat())
localTop = minOf(localTop, reserve.top.toFloat())
localRight = maxOf(localRight, reserve.right.toFloat())
localBottom = maxOf(localBottom, reserve.bottom.toFloat())
}
val affine = placementAffine(placement)
var left = Float.POSITIVE_INFINITY
var top = Float.POSITIVE_INFINITY
var right = Float.NEGATIVE_INFINITY
var bottom = Float.NEGATIVE_INFINITY
for (cornerIndex in 0 until 4) {
val cornerX = if (cornerIndex and 1 == 0) localLeft else localRight
val cornerY = if (cornerIndex and 2 == 0) localTop else localBottom
val pageX = affine[0] * cornerX + affine[1] * cornerY + affine[2]
val pageY = affine[3] * cornerX + affine[4] * cornerY + affine[5]
left = minOf(left, pageX)
top = minOf(top, pageY)
right = maxOf(right, pageX)
bottom = maxOf(bottom, pageY)
}
return PlacementFootprint(left, top, right, bottom)
}
/** The side of one occupancy block, in page pixels. */
private const val OCCUPANCY_BLOCK_SIDE = 8
/**
* A tile's opaque texels within its trim, one bit each, trim-local - a mover's painted region.
*
* @property LayerBounds trim The trim the mask covers, raster-local.
*/
class TileOpaqueMask private constructor(
val trim: LayerBounds,
private val words: LongArray,
) {
/**
* Whether the raster texel at ([tileX], [tileY]) is opaque; false outside the trim.
*
* @param Int tileX The texel column, raster-local.
* @param Int tileY The texel row, raster-local.
* @return Boolean True when the texel meets the mask's threshold.
*/
fun isOpaque(tileX: Int, tileY: Int): Boolean {
val column = tileX - trim.left
val row = tileY - trim.top
if (column < 0 || row < 0 || column >= trim.width || row >= trim.height) {
return false
}
val bitIndex = row * trim.width + column
return (words[bitIndex ushr 6] ushr (bitIndex and 63)) and 1L == 1L
}
companion object {
/**
* The mask of [raster]'s texels inside [trim] whose alpha reaches [alphaThreshold].
*
* @param DecodedImage raster The tile's decoded art.
* @param LayerBounds trim The sub-rectangle to mask, raster-local.
* @param Int alphaThreshold The alpha a texel needs to count as opaque.
* @return TileOpaqueMask The mask.
*/
fun of(raster: DecodedImage, trim: LayerBounds, alphaThreshold: Int): TileOpaqueMask {
val bitCount = trim.width * trim.height
val words = LongArray((bitCount + 63) ushr 6)
for (row in 0 until trim.height) {
val rowOffset = (trim.top + row) * raster.width + trim.left
for (column in 0 until trim.width) {
val alpha = raster.rgba[(rowOffset + column) * 4 + 3].toInt() and 0xFF
if (alpha >= alphaThreshold) {
val bitIndex = row * trim.width + column
words[bitIndex ushr 6] = words[bitIndex ushr 6] or (1L shl (bitIndex and 63))
}
}
}
return TileOpaqueMask(trim, words)
}
}
}
/**
* An integer pixel rectangle on a page, right and bottom exclusive.
*
* @property Int left The left edge.
* @property Int top The top edge.
* @property Int right The right edge, exclusive.
* @property Int bottom The bottom edge, exclusive.
*/
data class PixelRect(
val left: Int,
val top: Int,
val right: Int,
val bottom: Int,
) {
/**
* Whether ([x], [y]) lies inside.
*
* @param Int x The pixel column.
* @param Int y The pixel row.
* @return Boolean True when inside.
*/
fun contains(x: Int, y: Int): Boolean = x >= left && x < right && y >= top && y < bottom
}
/**
* The shown page's painted pixels - the bystanders' painted region as one surface.
*
* The composed page's alpha IS what is painted there (a bleed band carries none, so it reads empty), so no tile needs
* decoding: one pass over the page reduces it to a bitset of 8x8 blocks for fast rejection, and the
* exact alpha stays behind it for the pixels a sampled region actually touches. The rectangles a
* caller names are read as empty - the spots the movers are leaving.
*
* Holds the page's pixel buffer by reference; it is never written.
*
* @property Int width The page width in pixels.
* @property Int height The page height in pixels.
*/
class PageOccupancy private constructor(
val width: Int,
val height: Int,
private val rgba: ByteArray,
private val blockColumns: Int,
private val blockWords: LongArray,
private val excluded: List<PixelRect>,
) {
/**
* Whether the page pixel at ([x], [y]) is painted: on the page, outside every excluded
* rectangle, and not fully transparent.
*
* @param Int x The pixel column.
* @param Int y The pixel row.
* @return Boolean True when painted.
*/
fun isPainted(x: Int, y: Int): Boolean {
if (x < 0 || y < 0 || x >= width || y >= height) {
return false
}
for (rect in excluded) {
if (rect.contains(x, y)) {
return false
}
}
return (rgba[(y * width + x) * 4 + 3].toInt() and 0xFF) != 0
}
/**
* Whether the 8x8 block at ([blockX], [blockY]) holds any painted pixel - the cheap rejection the
* exact test hides behind. Excluded rectangles are not applied here; a block that overlaps one may
* answer true and the exact test then says no.
*
* @param Int blockX The block column.
* @param Int blockY The block row.
* @return Boolean True when the block may be painted.
*/
fun blockMayBePainted(blockX: Int, blockY: Int): Boolean {
val bitIndex = blockY * blockColumns + blockX
return (blockWords[bitIndex ushr 6] ushr (bitIndex and 63)) and 1L == 1L
}
/**
* Whether any painted pixel lies inside [region].
*
* Walks the blocks under the region's bounds, and only for a block that may be painted tests its
* pixels exactly against the region and the page.
*
* @param SampledRegion region The region to test.
* @return PixelRect? A one-pixel rectangle at the first painted pixel found, or null when none.
*/
fun firstPaintedPixelIn(region: SampledRegion): PixelRect? {
val bounds = region.bounds
val startX = floor(bounds.left).toInt().coerceAtLeast(0)
val endX = ceil(bounds.right).toInt().coerceAtMost(width)
val startY = floor(bounds.top).toInt().coerceAtLeast(0)
val endY = ceil(bounds.bottom).toInt().coerceAtMost(height)
if (startX >= endX || startY >= endY) {
return null
}
for (blockY in (startY / OCCUPANCY_BLOCK_SIDE)..((endY - 1) / OCCUPANCY_BLOCK_SIDE)) {
for (blockX in (startX / OCCUPANCY_BLOCK_SIDE)..((endX - 1) / OCCUPANCY_BLOCK_SIDE)) {
if (!blockMayBePainted(blockX, blockY)) {
continue
}
val pixelStartX = maxOf(startX, blockX * OCCUPANCY_BLOCK_SIDE)
val pixelEndX = minOf(endX, (blockX + 1) * OCCUPANCY_BLOCK_SIDE)
val pixelStartY = maxOf(startY, blockY * OCCUPANCY_BLOCK_SIDE)
val pixelEndY = minOf(endY, (blockY + 1) * OCCUPANCY_BLOCK_SIDE)
for (y in pixelStartY until pixelEndY) {
for (x in pixelStartX until pixelEndX) {
if (region.contains(x + 0.5f, y + 0.5f) && isPainted(x, y)) {
return PixelRect(x, y, x + 1, y + 1)
}
}
}
}
}
return null
}
companion object {
/**
* The occupancy of [page], with [excluded] read as empty.
*
* @param DecodedImage page The shown page.
* @param List<PixelRect> excluded Rectangles to read as unpainted (the movers' old spots).
* @return PageOccupancy The occupancy.
*/
fun of(page: DecodedImage, excluded: List<PixelRect>): PageOccupancy {
val blockColumns = (page.width + OCCUPANCY_BLOCK_SIDE - 1) / OCCUPANCY_BLOCK_SIDE
val blockRows = (page.height + OCCUPANCY_BLOCK_SIDE - 1) / OCCUPANCY_BLOCK_SIDE
val blockWords = LongArray((blockColumns * blockRows + 63) ushr 6)
for (y in 0 until page.height) {
val rowOffset = y * page.width
val blockRow = (y / OCCUPANCY_BLOCK_SIDE) * blockColumns
for (x in 0 until page.width) {
if (page.rgba[(rowOffset + x) * 4 + 3].toInt() != 0) {
val bitIndex = blockRow + x / OCCUPANCY_BLOCK_SIDE
blockWords[bitIndex ushr 6] = blockWords[bitIndex ushr 6] or (1L shl (bitIndex and 63))
}
}
}
return PageOccupancy(page.width, page.height, page.rgba, blockColumns, blockWords, excluded)
}
}
}
/**
* The coverage of a tile's meshes in the tile's own pixel frame, one bit per pixel over the meshes'
* bounding box - which may extend past the raster, since a mesh typically overhangs its art.
*
* @property LayerBounds bounds The box the bits cover, raster-local (left / top may be negative).
*/
class TileMeshMask private constructor(
val bounds: LayerBounds,
private val words: LongArray,
) {
/**
* Whether the tile pixel at ([tileX], [tileY]) is covered by a triangle (within the one-pixel
* conservative margin); false outside the box.
*
* @param Int tileX The pixel column, raster-local.
* @param Int tileY The pixel row, raster-local.
* @return Boolean True when covered.
*/
fun isCovered(tileX: Int, tileY: Int): Boolean {
val column = tileX - bounds.left
val row = tileY - bounds.top
if (column < 0 || row < 0 || column >= bounds.width || row >= bounds.height) {
return false
}
val bitIndex = row * bounds.width + column
return (words[bitIndex ushr 6] ushr (bitIndex and 63)) and 1L == 1L
}
companion object {
/**
* The mask of [triangles] (art-pixel coordinates, nine floats per triangle: three interleaved
* (x, y) corners) filled by pixel-center test and dilated by one pixel in every direction, so a
* bilinear sampler reading half a texel past any covered point is inside it. Every corner's own
* pixel is marked too, so a sliver too thin to cover a center still contributes.
*
* @param List<FloatArray> triangles The triangles, art-local.
* @return TileMeshMask? The mask, or null when there are no triangles.
*/
fun of(triangles: List<FloatArray>): TileMeshMask? {
if (triangles.isEmpty()) {
return null
}
var minX = Float.POSITIVE_INFINITY
var minY = Float.POSITIVE_INFINITY
var maxX = Float.NEGATIVE_INFINITY
var maxY = Float.NEGATIVE_INFINITY
for (triangle in triangles) {
for (cornerIndex in 0 until 3) {
minX = minOf(minX, triangle[cornerIndex * 2])
maxX = maxOf(maxX, triangle[cornerIndex * 2])
minY = minOf(minY, triangle[cornerIndex * 2 + 1])
maxY = maxOf(maxY, triangle[cornerIndex * 2 + 1])
}
}
// One pixel of margin for the dilation on every side.
val left = floor(minX).toInt() - 1
val top = floor(minY).toInt() - 1
val width = ceil(maxX).toInt() + 1 - left
val height = ceil(maxY).toInt() + 1 - top
val raw = LongArray((width * height + 63) ushr 6)
fun mark(column: Int, row: Int) {
if (column < 0 || row < 0 || column >= width || row >= height) {
return
}
val bitIndex = row * width + column
raw[bitIndex ushr 6] = raw[bitIndex ushr 6] or (1L shl (bitIndex and 63))
}
for (triangle in triangles) {
val x0 = triangle[0] - left
val y0 = triangle[1] - top
val x1 = triangle[2] - left
val y1 = triangle[3] - top
val x2 = triangle[4] - left
val y2 = triangle[5] - top
mark(floor(x0).toInt(), floor(y0).toInt())
mark(floor(x1).toInt(), floor(y1).toInt())
mark(floor(x2).toInt(), floor(y2).toInt())
val area = (x1 - x0) * (y2 - y0) - (x2 - x0) * (y1 - y0)
if (area == 0f) {
continue
}
val startColumn = floor(minOf(x0, x1, x2)).toInt().coerceAtLeast(0)
val endColumn = ceil(maxOf(x0, x1, x2)).toInt().coerceAtMost(width - 1)
val startRow = floor(minOf(y0, y1, y2)).toInt().coerceAtLeast(0)
val endRow = ceil(maxOf(y0, y1, y2)).toInt().coerceAtMost(height - 1)
val orientation = if (area > 0f) 1f else -1f
for (row in startRow..endRow) {
val centerY = row + 0.5f
for (column in startColumn..endColumn) {
val centerX = column + 0.5f
val edge0 = ((x1 - x0) * (centerY - y0) - (y1 - y0) * (centerX - x0)) * orientation
val edge1 = ((x2 - x1) * (centerY - y1) - (y2 - y1) * (centerX - x1)) * orientation
val edge2 = ((x0 - x2) * (centerY - y2) - (y0 - y2) * (centerX - x2)) * orientation
if (edge0 >= 0f && edge1 >= 0f && edge2 >= 0f) {
mark(column, row)
}
}
}
}
// Dilate by one pixel: a bit set anywhere in the 3x3 neighborhood sets the pixel.
val dilated = LongArray(raw.size)
for (row in 0 until height) {
for (column in 0 until width) {
var covered = false
for (rowOffset in -1..1) {
val neighborRow = row + rowOffset
if (neighborRow < 0 || neighborRow >= height) {
continue
}
for (columnOffset in -1..1) {
val neighborColumn = column + columnOffset
if (neighborColumn < 0 || neighborColumn >= width) {
continue
}
val bitIndex = neighborRow * width + neighborColumn
if ((raw[bitIndex ushr 6] ushr (bitIndex and 63)) and 1L == 1L) {
covered = true
}
}
}
if (covered) {
val bitIndex = row * width + column
dilated[bitIndex ushr 6] = dilated[bitIndex ushr 6] or (1L shl (bitIndex and 63))
}
}
}
return TileMeshMask(LayerBounds(left, top, width, height), dilated)
}
}
}
/**
* The triangles of every drawable bound to [tileId], in the tile's own pixel frame - the same
* uv-to-art conversion [meshReserveByTile] measures with.
*
* @param PuppetModel model The model.
* @param AtlasTileId tileId The tile.
* @return List<FloatArray> The triangles, nine floats each; empty when nothing measurable is bound.
*/
fun meshTrianglesOf(model: PuppetModel, tileId: AtlasTileId): List<FloatArray> {
val tile = model.atlas.tileById[tileId] ?: return emptyList()
val storedToArt = model.atlas.storedToArtAffineForTile(tileId) ?: return emptyList()
val triangles = ArrayList<FloatArray>()
for (drawable in model.drawables) {
if (drawable.atlasTileId != tileId) {
continue
}
val mesh = drawable.mesh ?: continue
if (mesh.uvs.size < 2 || mesh.indices.size < 3) {
continue
}
val artUvs = applyUvAffine(mesh.uvs, storedToArt)
val vertexCount = artUvs.size / 2
var indexOffset = 0
while (indexOffset + 2 < mesh.indices.size) {
val cornerA = mesh.indices[indexOffset]
val cornerB = mesh.indices[indexOffset + 1]
val cornerC = mesh.indices[indexOffset + 2]
indexOffset += 3
if (cornerA >= vertexCount || cornerB >= vertexCount || cornerC >= vertexCount) {
continue
}
triangles.add(
floatArrayOf(
artUvs[cornerA * 2] * tile.width,
artUvs[cornerA * 2 + 1] * tile.height,
artUvs[cornerB * 2] * tile.width,
artUvs[cornerB * 2 + 1] * tile.height,
artUvs[cornerC * 2] * tile.width,
artUvs[cornerC * 2 + 1] * tile.height,
),
)
}
}
return triangles
}
/**
* The coverage mask of every mesh bound to [tileId], or null when the tile has no measurable mesh.
*
* @param PuppetModel model The model.
* @param AtlasTileId tileId The tile.
* @return TileMeshMask? The mask.
*/
fun meshMaskOf(model: PuppetModel, tileId: AtlasTileId): TileMeshMask? = TileMeshMask.of(meshTrianglesOf(model, tileId))
/**
* A tile's sampled region on the page: the coverage of its meshes carried through its placement and
* tested exactly - a page point maps back into the tile through the placement inverse and reads the
* coverage bit, so a rotated tile's region stays its true shape.
*
* @property AtlasPlacement placement The tile's placement.
* @property TileMeshMask mask The meshes' coverage, raster-local.
*/
class SampledRegion(
val placement: AtlasPlacement,
val mask: TileMeshMask,
) {
private val pageToTile: FloatArray? = inversePlacementAffine(placement)
/** The region's page-space bounds (the coverage box through the placement). */
val bounds: PlacementFootprint = placementFootprint(placement, mask.bounds, reserve = null)
/**
* Whether the page point ([pageX], [pageY]) lands on a covered tile pixel.
*
* @param Float pageX The page x.
* @param Float pageY The page y.
* @return Boolean True when covered; false for a degenerate placement.
*/
fun contains(pageX: Float, pageY: Float): Boolean {
val inverse = pageToTile ?: return false
val tileX = inverse[0] * pageX + inverse[1] * pageY + inverse[2]
val tileY = inverse[3] * pageX + inverse[4] * pageY + inverse[5]
return mask.isCovered(floor(tileX).toInt(), floor(tileY).toInt())
}
}
/**
* Whether [region] samples any opaque texel of [mask] placed at [placement], the composer's extrusion
* band counted as painted (a page pixel within [extrude] of the trim reads the nearest edge texel).
*
* Scans the intersection of the region's bounds with the placed trim's bounds grown by the band, and
* tests each pixel center both ways: inside the region, and on an opaque texel through the mask
* placement's inverse.
*
* @param SampledRegion region The sampling tile's region.
* @param AtlasPlacement placement Where the painting tile sits.
* @param TileOpaqueMask mask The painting tile's opaque texels.
* @param Int extrude The composer's edge extrusion.
* @return Boolean True when the region samples paint.
*/
fun sampledRegionHitsMask(
region: SampledRegion,
placement: AtlasPlacement,
mask: TileOpaqueMask,
extrude: Int,
): Boolean {
val painted = placementFootprint(placement, mask.trim, reserve = null).expanded(extrude.toFloat())
val bounds = region.bounds
if (!bounds.overlaps(painted)) {
return false
}
val inverse = inversePlacementAffine(placement) ?: return false
val forward = placementAffine(placement)
val startX = floor(maxOf(bounds.left, painted.left)).toInt()
val endX = ceil(minOf(bounds.right, painted.right)).toInt()
val startY = floor(maxOf(bounds.top, painted.top)).toInt()
val endY = ceil(minOf(bounds.bottom, painted.bottom)).toInt()
val trim = mask.trim
val trimLeft = trim.left.toFloat()
val trimTop = trim.top.toFloat()
val trimRight = (trim.left + trim.width).toFloat()
val trimBottom = (trim.top + trim.height).toFloat()
val extrudeSquared = extrude.toFloat() * extrude.toFloat()
for (y in startY until endY) {
val centerY = y + 0.5f
for (x in startX until endX) {
val centerX = x + 0.5f
if (!region.contains(centerX, centerY)) {
continue
}
val tileX = inverse[0] * centerX + inverse[1] * centerY + inverse[2]
val tileY = inverse[3] * centerX + inverse[4] * centerY + inverse[5]
val clampedX = tileX.coerceIn(trimLeft, trimRight)
val clampedY = tileY.coerceIn(trimTop, trimBottom)
if (clampedX != tileX || clampedY != tileY) {
if (extrude == 0) {
continue
}
val backX = forward[0] * clampedX + forward[1] * clampedY + forward[2]
val backY = forward[3] * clampedX + forward[4] * clampedY + forward[5]
val deltaX = backX - centerX
val deltaY = backY - centerY
if (deltaX * deltaX + deltaY * deltaY > extrudeSquared) {
continue
}
}
val texelX = floor(clampedX).toInt().coerceIn(trim.left, trim.left + trim.width - 1)
val texelY = floor(clampedY).toInt().coerceIn(trim.top, trim.top + trim.height - 1)
if (mask.isOpaque(texelX, texelY)) {
return true
}
}
}
return false
}
@@ -0,0 +1,4 @@
package org.umamo.render
/** A decoded RGBA image (top row first), ready for GL upload. */
class DecodedImage(val rgba: ByteArray, val width: Int, val height: Int)
@@ -0,0 +1,233 @@
package org.umamo.render
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.analyzeAlpha
import org.umamo.format.atlas.AtlasPackItem
import org.umamo.format.atlas.AtlasPackOptions
import org.umamo.format.atlas.AtlasPackPlacement
import org.umamo.format.atlas.AtlasTilePlacement
import org.umamo.format.atlas.composeAtlasPagesAffine
import org.umamo.format.raster.RasterImage
import org.umamo.runtime.model.AtlasComposition
import org.umamo.runtime.model.AtlasPlacement
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.placementAffine
/*
* Page derivation for a GENERATED atlas: the pixels a model's authored placements denote, composed
* from the source art. An imported document's original pages never come through here while its
* atlas is the baseline - the session's page resolver short-circuits that value to the document's own
* decoded pages - but the moment a rigger moves one tile the whole page set derives from here, imported
* placements included, so nothing in this file may assume the packer authored every placement.
*
* Two steps on purpose: PLAN resolves what will be drawn (every placed tile's pixels, trim, and page
* affine) without touching a page buffer, and COMPOSE draws it. The plan is cheap and is also the
* footprint inventory the placement gizmo reads before it lets a gesture commit, so the drag and the
* resolver cannot disagree about what a placement will paint.
*/
/**
* The rotation a placement carries for one of the packer's counter-clockwise quarter turns.
*
* [placementAffine] turns by +rotationDegrees with the matrix ((cos, -sin), (sin, cos)) in the page's
* y-down frame; the packer's turn sends trim-local (u, v) to (v, -u), which is that matrix at -90.
*/
private const val QUARTER_TURN_DEGREES = -90f
/**
* The trim a derivation draws of [raster]: the packer's own opaque-bounds analysis at
* [alphaThreshold], or null when nothing in the raster is opaque.
*
* @param DecodedImage raster The tile's decoded source art.
* @param Int alphaThreshold The atlas's trim threshold (`PuppetAtlas.composition`).
* @return LayerBounds? The opaque sub-rectangle, raster-local.
*/
public fun derivedTileTrim(raster: DecodedImage, alphaThreshold: Int): LayerBounds? =
analyzeAlpha(raster.width, raster.height, raster.rgba, alphaThreshold)?.opaqueBounds
/**
* The composition policy a pack under [options] leaves on the model, so the derivation trims and
* bleeds exactly as the pack did.
*
* @param AtlasPackOptions options The options the pack ran with.
* @return AtlasComposition The two derivation-relevant options, as model state.
*/
fun atlasCompositionOf(options: AtlasPackOptions): AtlasComposition = AtlasComposition(options.alphaThreshold, options.extrude)
/**
* An [AtlasPackPlacement] lowered onto the model's placement transform: the trim origin folds into
* the position and scale stays 1.
*
* Upright, the tile's origin sits trimLeft / trimTop above and left of the packed rect. Turned, the
* packer sends trim-local (u, v) to (pageX + v, pageY + trimWidth - u), so over the untrimmed tile
* frame the origin lands at (pageX - trimTop, pageY + trimWidth + trimLeft) under a -90 degree
* rotation - the affine the composer's own exact quarter-turn path recognises, so a turned pack
* derives through the packer's blit. Any other turn count is a packer contract violation.
*
* @param AtlasPackPlacement packPlacement Where the packer put one tile.
* @return AtlasPlacement The equivalent authored placement.
*/
fun atlasPlacementFromPack(packPlacement: AtlasPackPlacement): AtlasPlacement {
require(packPlacement.quarterTurns in 0..1) {
"tile '${packPlacement.key}' has an unsupported rotation: ${packPlacement.quarterTurns} quarter turns"
}
return if (packPlacement.quarterTurns == 0) {
AtlasPlacement(
pageIndex = packPlacement.pageIndex,
positionX = (packPlacement.pageX - packPlacement.trimLeft).toFloat(),
positionY = (packPlacement.pageY - packPlacement.trimTop).toFloat(),
scaleX = 1f,
scaleY = 1f,
rotationDegrees = 0f,
)
} else {
AtlasPlacement(
pageIndex = packPlacement.pageIndex,
positionX = (packPlacement.pageX - packPlacement.trimTop).toFloat(),
positionY = (packPlacement.pageY + packPlacement.trimWidth + packPlacement.trimLeft).toFloat(),
scaleX = 1f,
scaleY = 1f,
rotationDegrees = QUARTER_TURN_DEGREES,
)
}
}
/**
* What a derivation will compose: every placed tile's pixels, trim, and page affine, resolved
* before any page buffer is allocated.
*
* @property List items The placed tiles' pixels, keyed by tile id.
* @property List placements Each placed tile's trim and tile-to-page affine.
* @property Map trimByTile Each drawn tile's trim, for callers reasoning about footprints.
*/
class AtlasDerivationPlan(
val items: List<AtlasPackItem>,
val placements: List<AtlasTilePlacement>,
val trimByTile: Map<AtlasTileId, LayerBounds>,
)
/**
* Resolves what [model]'s atlas denotes without composing a pixel.
*
* Null when the atlas cannot be derived at all: a placement naming a page the atlas lacks, art that
* will not decode, or art whose size disagrees with its tile - faults in the document, not in the
* placement. A placed tile with nothing opaque is skipped rather than refused (there is nothing to
* draw), and scale, rotation, fractional positions, and footprints past the page edge all derive:
* the composer resamples and clips them.
*
* Thread-safe: reads pixels through [SourceArtRasters.decodeRaster] and shares nothing, so callers
* run it off the UI thread.
*
* @param PuppetModel model The model whose atlas to resolve.
* @param SourceArtRasters artRasters The source-art pixel store.
* @return AtlasDerivationPlan? The plan, or null when the atlas cannot be derived.
*/
fun planAtlasDerivation(model: PuppetModel, artRasters: SourceArtRasters): AtlasDerivationPlan? {
val atlas = model.atlas
val items = ArrayList<AtlasPackItem>()
val placements = ArrayList<AtlasTilePlacement>()
val trimByTile = HashMap<AtlasTileId, LayerBounds>()
for (tile in atlas.tiles) {
val placement = tile.placement ?: continue
if (placement.pageIndex !in atlas.pages.indices) {
return null
}
val raster = artRasters.decodeRaster(tile.id) ?: return null
if (raster.width != tile.width || raster.height != tile.height) {
return null
}
// The packer trimmed each tile to its opaque bounds before placing it; the placement holds only
// the untrimmed origin, so the same analysis on the same pixels, under the threshold the atlas
// records, reconstructs the trim exactly.
val trim = derivedTileTrim(raster, atlas.composition.alphaThreshold) ?: continue
trimByTile[tile.id] = trim
items.add(AtlasPackItem(tile.id.raw, raster.width, raster.height, raster.rgba))
placements.add(AtlasTilePlacement(tile.id.raw, placement.pageIndex, trim, placementAffine(placement)))
}
return AtlasDerivationPlan(items, placements, trimByTile)
}
/**
* The [PuppetTextures] a generated atlas value denotes: pages composed from the model's tiles,
* placements, and decoded source art.
*
* For a page set built here, the model's page numbering and the renderer's COINCIDE by construction:
* [PuppetTextures.atlases] is index-parallel to `PuppetAtlas.pages`, and the drawable map carries
* each placement's own page index. That guarantee holds for GENERATED sets only - an imported
* document's two numberings stay independent (see [AtlasPlacement]), because its renderer pages were
* collected by a different walk than its document pages.
*
* A placement the packer authored (an integer translation with room for its extrusion) composes
* through the packer's own blit, byte-identical to the pages the repack produced; every other
* placement resamples through the affine composer. Null exactly when [planAtlasDerivation] is null;
* the caller treats that as "keep showing the pages you have".
*
* Thread-safe, like the plan.
*
* @param PuppetModel model The model whose atlas to compose.
* @param SourceArtRasters artRasters The source-art pixel store.
* @param Boolean premultipliedAlpha The document's texture-convention flag, carried through.
* @return PuppetTextures? The composed page set, or null when the atlas cannot be derived.
*/
fun deriveAtlasTextures(
model: PuppetModel,
artRasters: SourceArtRasters,
premultipliedAlpha: Boolean,
): PuppetTextures? {
val plan = planAtlasDerivation(model, artRasters) ?: return null
val atlas = model.atlas
val pages =
composeAtlasPagesAffine(
pageWidths = IntArray(atlas.pages.size) { pageIndex -> atlas.pages[pageIndex].width },
pageHeights = IntArray(atlas.pages.size) { pageIndex -> atlas.pages[pageIndex].height },
items = plan.items,
placements = plan.placements,
extrude = atlas.composition.extrude,
)
return generatedPuppetTextures(pages, model, premultipliedAlpha)
}
/**
* The [PuppetTextures] a GENERATED page set is: [pages] wrapped as decoded images, index-parallel to
* `PuppetAtlas.pages`, under the drawable map of [generatedAtlasIndexByDrawableId].
*
* One function used by the repack (from the pack it just ran), the derivation above (for an undone
* generation), and the export gate, so no caller assembles the wrapper on its own and the page cache's
* identity-keyed sets are always built the same way.
*
* @param List pages The composed pages, in the model's page order.
* @param PuppetModel model The model whose bindings key the drawable map.
* @param Boolean premultipliedAlpha The document's texture-convention flag, carried through.
* @return PuppetTextures The page set.
*/
fun generatedPuppetTextures(
pages: List<RasterImage>,
model: PuppetModel,
premultipliedAlpha: Boolean,
): PuppetTextures =
PuppetTextures(
atlases = pages.map { page -> DecodedImage(page.rgba, page.width, page.height) },
atlasIndexByDrawableId = generatedAtlasIndexByDrawableId(model),
premultipliedAlpha = premultipliedAlpha,
)
/**
* The drawable-to-page map a GENERATED page set carries: every drawable bound to a placed tile maps
* to that tile's own page index, so the map shares the model's page numbering.
*
* @param PuppetModel model The model whose bindings to map.
* @return Map The renderer's drawable-to-page lookup.
*/
fun generatedAtlasIndexByDrawableId(model: PuppetModel): Map<String, Int> {
val placementByTileId = model.atlas.tiles.associateBy({ tile -> tile.id }, { tile -> tile.placement })
val atlasIndexByDrawableId = HashMap<String, Int>()
for (drawable in model.drawables) {
val tileId = drawable.atlasTileId ?: continue
val placement = placementByTileId[tileId] ?: continue
// Keyed the way the renderer looks it up: a duplicated drawable resolves its page through the
// drawable it was duplicated from (Drawable.textureSourceId), and shared sources share a tile.
atlasIndexByDrawableId[(drawable.textureSourceId ?: drawable.id).raw] = placement.pageIndex
}
return atlasIndexByDrawableId
}
@@ -0,0 +1,67 @@
package org.umamo.render
import org.umamo.format.raster.RasterImage
import org.umamo.format.raster.setOpaqueAlphaInPlace
import org.umamo.format.raster.unpremultiplyInPlace
/**
* What a puppet frame is drawn over.
*
* The viewport always draws over its grid; an image captured from the renderer chooses, because a
* transparent or flat background is what makes the capture usable outside the editor.
*/
sealed interface FrameBackdrop {
/**
* The themed grid backdrop the viewport shows, with the world-origin axes when the renderer has them
* turned on.
*/
data object Grid : FrameBackdrop
/**
* A flat fill, as premultiplied 0..1 RGBA. Transparent is all four at zero; an opaque color has alpha
* 1, where premultiplied and straight color are the same. No grid and no axes are drawn.
*
* @property Float red The fill's red.
* @property Float green The fill's green.
* @property Float blue The fill's blue.
* @property Float alpha The fill's alpha.
*/
data class Clear(
val red: Float,
val green: Float,
val blue: Float,
val alpha: Float,
) : FrameBackdrop
companion object {
/** Nothing at all: every pixel the puppet does not cover stays fully transparent. */
val Transparent: FrameBackdrop = Clear(0f, 0f, 0f, 0f)
}
}
/**
* Turns a premultiplied capture drawn over [backdrop] into the straight-alpha image a file stores, in place.
*
* Over an opaque backdrop every pixel is opaque, so the color is already straight and only the alpha
* channel is set to 255. Over anything with coverage to spare (transparency, or a translucent fill) the
* color divides back out by its alpha.
*
* Consumes the capture: its own buffer is converted and the same image returned, because a capture can be
* a gigabyte and a converted copy would double that. The caller must own the pixels.
*
* @param FrameBackdrop backdrop What the capture was drawn over.
* @return RasterImage This image, now straight alpha, top row first.
*/
fun RasterImage.capturedOver(backdrop: FrameBackdrop): RasterImage {
val opaque =
when (backdrop) {
FrameBackdrop.Grid -> true
is FrameBackdrop.Clear -> backdrop.alpha >= 1f
}
if (opaque) {
setOpaqueAlphaInPlace()
} else {
unpremultiplyInPlace()
}
return this
}
@@ -0,0 +1,77 @@
package org.umamo.render
/**
* The three colors of the viewport grid backdrop, as 0..1 linear RGB triples: the flat canvas fill, the
* major grid line color, and the minor (subdivision) grid line color. Kept as plain floats (not a Compose
* Color) so :render stays free of any UI dependency; the editor maps its themed palette into this at the
* call site. [Classic] is a neutral grey grid, used as the default so a caller that does not theme the
* backdrop still gets a sensible surface.
*
* ビューポートのグリッド背景の 3 色(0..1 の RGB)。背景・主線・副線。:render を UI 非依存に保つため素の float。
*
* @property Float backgroundRed Red of the flat canvas fill.
* @property Float backgroundGreen Green of the flat canvas fill.
* @property Float backgroundBlue Blue of the flat canvas fill.
* @property Float majorRed Red of the major grid line.
* @property Float majorGreen Green of the major grid line.
* @property Float majorBlue Blue of the major grid line.
* @property Float minorRed Red of the minor (subdivision) grid line.
* @property Float minorGreen Green of the minor grid line.
* @property Float minorBlue Blue of the minor grid line.
*/
data class GridColors(
val backgroundRed: Float,
val backgroundGreen: Float,
val backgroundBlue: Float,
val majorRed: Float,
val majorGreen: Float,
val majorBlue: Float,
val minorRed: Float,
val minorGreen: Float,
val minorBlue: Float,
) {
companion object {
/** A neutral dark-grey grid: #2E2E2E fill, #484848 major lines, #3A3A3A minor lines. */
val Classic: GridColors =
GridColors(
0.204f,
0.204f,
0.204f,
0.317f,
0.317f,
0.317f,
0.270f,
0.270f,
0.270f,
)
}
}
/**
* The two world-axis line colors, as 0..1 linear RGB triples - the red X axis and the blue Z axis
* drawn through the world origin behind the puppet (the project's display convention is Y+ forward,
* Z+ up, so the vertical world axis is presented as Z). Plain floats for the same reason as
* [GridColors]: :render stays free of any UI dependency.
*
* ワールド軸線の 2 色(0..1 の RGB)。横が赤い X 軸、縦が青い Z 軸(表示規約は Y+ 前、Z+ 上)。
*
* @property Float xRed Red of the horizontal X axis line.
* @property Float xGreen Green of the horizontal X axis line.
* @property Float xBlue Blue of the horizontal X axis line.
* @property Float zRed Red of the vertical Z axis line.
* @property Float zGreen Green of the vertical Z axis line.
* @property Float zBlue Blue of the vertical Z axis line.
*/
data class WorldAxisColors(
val xRed: Float,
val xGreen: Float,
val xBlue: Float,
val zRed: Float,
val zGreen: Float,
val zBlue: Float,
) {
companion object {
/** Blender-like axis colors: a muted red X and a muted blue Z. */
val Classic: WorldAxisColors = WorldAxisColors(0.84f, 0.31f, 0.36f, 0.31f, 0.44f, 0.85f)
}
}
@@ -0,0 +1,128 @@
package org.umamo.render
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.atlasBindingFor
import org.umamo.runtime.model.layerUvAffineOf
/**
* One drawable's source-artwork draw: which image it samples, and the affine carrying its stored
* texture coordinates into that image's frame.
*
* @property String layerKey The artwork this drawable samples, keyed into [LayerRasterBatch.rastersByLayerKey].
* @property FloatArray uvAffine The 2x3 row-major stored-to-artwork affine (see `layerUvAffineOf`).
*/
class DrawableLayerDraw(val layerKey: String, val uvAffine: FloatArray)
/**
* Which artwork every drawable would display from, and what each image would cost to hold - the
* mapping half of source-artwork display, carrying no pixels at all.
*
* ALWAYS COMPLETE: it covers every drawable whose art this document can recover, whether or not that
* art is currently decoded or resident on the GPU. That completeness is what lets the renderer bound
* residency without losing information - a layer dropped for budget can be promoted again later
* because its mapping never went away, and [unresolvedDrawableCount] keeps meaning "no artwork
* exists" rather than drifting into "not resident right now".
*
* Cheap to build and cheap to hold: [layerByteCostByKey] comes from the model's atlas tile sizes, so
* the cost of every image is known BEFORE any of them decode, which is what makes a budget
* enforceable up front instead of after the memory is already spent.
*
* A drawable absent from [drawsByDrawableId] renders from its atlas page as usual, so a document
* whose artwork is only partly recoverable still draws whole.
*
* @property Map<String, DrawableLayerDraw> drawsByDrawableId Each drawable's draw, by raw drawable id.
* @property Map<String, Long> layerByteCostByKey What each distinct image costs decoded, in bytes.
* Keyed by LAYER, not by drawable: duplicated art is shared, so a layer is paid for once.
* @property Int unresolvedDrawableCount How many meshed drawables have no recoverable artwork at all
* and so keep displaying from the atlas. Reported rather than hidden: a puppet drawn mostly from
* its atlas should not look like one drawn from its artwork.
*/
class LayerDrawPlan(
val drawsByDrawableId: Map<String, DrawableLayerDraw>,
val layerByteCostByKey: Map<String, Long>,
val unresolvedDrawableCount: Int = 0,
) {
/** True when there is nothing to display from, so the puppet stays on the atlas. */
val isEmpty: Boolean get() = drawsByDrawableId.isEmpty()
/**
* Which drawables draw over any of the given layers.
*
* @param Set<String> layerKeys The layers in question.
* @return Set<String> The raw ids of the drawables mapped onto them.
*/
fun drawableIdsUsing(layerKeys: Set<String>): Set<String> =
drawsByDrawableId.filterValues { draw -> draw.layerKey in layerKeys }.keys
companion object {
/** The empty plan: display from the atlas. */
val EMPTY: LayerDrawPlan = LayerDrawPlan(emptyMap(), emptyMap())
}
}
/**
* A delivery of decoded artwork answering what the renderer asked for - the pixel half, transient by
* design.
*
* Pixels arrive in batches rather than as one complete set, and THAT is what keeps this affordable:
* the producer decodes a chunk, hands it over, and drops its reference before decoding the next, so
* the heap holds one chunk rather than the document's whole artwork. A rig whose layers would be a
* gigabyte decoded costs a few tens of megabytes to stream.
*
* Batches are additive and order-independent - the renderer uploads whatever a batch carries that its
* current plan still maps, and ignores the rest - so a late batch from a superseded plan is harmless
* rather than something to detect.
*
* @property Map<String, DecodedImage> rastersByLayerKey The decoded images, by layer key.
* @property Set<String> undecodableLayerKeys Layers whose pixels would not decode. Reported so the
* drawables over them can be counted as artwork-less rather than merely absent from this batch.
*/
class LayerRasterBatch(
val rastersByLayerKey: Map<String, DecodedImage>,
val undecodableLayerKeys: Set<String> = emptySet(),
)
/**
* Works out which source artwork each drawable would display from, and what each image would cost.
*
* Decodes NOTHING. It reads only the model's atlas - tile sizes and placements - so it is cheap
* enough to build eagerly for the whole document and to rebuild whenever the drawable set or a
* placement changes. Deciding the mapping separately from paying for the pixels is what lets a budget
* be applied before any memory is spent, and what keeps a budget-evicted layer promotable later.
*
* Safe on a background thread: it reads only the immutable model and touches neither the document's
* decode cache nor the device.
*
* A drawable is left out (and counted in [LayerDrawPlan.unresolvedDrawableCount]) when the document
* retains no art for it or when its placement will not invert. A layer whose pixels turn out not to
* decode is NOT known here - that surfaces later, from the batch that tried, so this count means
* exactly "no artwork exists" and never "not decoded yet".
*
* @param PuppetModel model The puppet whose drawables need artwork.
* @return LayerDrawPlan Each drawable's mapping plus the per-layer byte cost.
*/
fun buildLayerDrawPlan(model: PuppetModel): LayerDrawPlan {
if (model.atlas.tiles.isEmpty()) {
return LayerDrawPlan.EMPTY
}
val drawsByDrawableId = HashMap<String, DrawableLayerDraw>()
val layerByteCostByKey = HashMap<String, Long>()
var unresolved = 0
for (drawable in model.drawables) {
if (drawable.mesh == null) {
continue
}
val binding = model.atlasBindingFor(drawable)
val tile = drawable.atlasTileId?.let { tileId -> model.atlas.tileById[tileId] }
val affine = if (binding != null && tile != null) layerUvAffineOf(binding, tile.width, tile.height) else null
if (binding == null || tile == null || affine == null) {
unresolved++
continue
}
// Four bytes per pixel: what the image occupies once decoded to RGBA and again once uploaded,
// which is the quantity the residency budget is denominated in.
layerByteCostByKey[binding.layerKey] = tile.width.toLong() * tile.height.toLong() * 4L
drawsByDrawableId[drawable.id.raw] = DrawableLayerDraw(binding.layerKey, affine)
}
return LayerDrawPlan(drawsByDrawableId, layerByteCostByKey, unresolved)
}
@@ -0,0 +1,314 @@
package org.umamo.render
import org.umamo.render.eval.CpuDeformationEvaluator
import org.umamo.render.eval.DeformedGeometry
import org.umamo.render.eval.drawableSpaceMapping
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshDeltaForm
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PuppetModel
import kotlin.math.max
import kotlin.math.min
/** The warp inverse's neutral seed: the middle of the normalized [0,1] lattice. */
private const val LATTICE_CENTRE: Float = 0.5f
/**
* Rewrites each drawable's rest mesh to its default-pose canvas-space geometry, matching the CMO3
* convention the editor is built on.
*
* The runtime convention (set by CMO3, verified against the corpus): Drawable.mesh.positions is the
* EDITABLE canvas-space geometry - what the gizmo overlay edits and the viewport maps gestures into -
* while each MeshForm's absolute positions (base + delta) live in the drawable's PARENT-DEFORMER
* space. The deformation eval only ever sees `base + Σ wᵢ·Δᵢ` with weights summing to 1, so the base
* cancels and this mixed-space encoding is exact, not an approximation.
*
* A `.moc3` stores only the parent-space keyforms, so :interop's `Moc3Import` can give
* a warp/rotation-parented drawable nothing better than a parent-local base. This pass finishes the
* import: it evaluates the default pose through the validated deformer cascade (glue excluded - the
* weld is a render-time effect, not rest geometry), takes the pre-Y-negation canvas positions as the
* new base, and re-expresses every keyform delta against it so `base + delta` still reconstructs the
* same parent-space absolutes. Drawables the raw default pose hides (a keyform axis whose keys do
* not bracket the driving parameter's default - the toggle-part authoring pattern) get a second
* evaluation at a pose with those parameters clamped into their axes' key ranges, so their rest
* meshes still land in canvas space. It lives in `:render` (not `:runtime`) because it is the
* evaluator that turns parent-space keyforms into canvas geometry.
*
* @param PuppetModel model An imported model whose rest meshes may be parent-local (a MOC3 import).
* @return PuppetModel The model with canvas-space rest meshes (a drawable that stays hidden even at
* the clamped pose keeps its parent-local base, which still evaluates correctly).
*/
fun restMeshesToCanvasSpace(model: PuppetModel): PuppetModel {
val preGlueModel = model.copy(glues = emptyList())
val evaluator = CpuDeformationEvaluator()
val defaultPose = evaluator.evaluate(preGlueModel, emptyMap())
// Second chance for drawables absent from the raw default pose: clamp every involved parameter
// into its axes' key ranges and evaluate once more. Only the still-missing drawables read from
// this pose, so in-range drawables keep their true default geometry.
val fallback = defaultPoseFallbackFor(model, defaultPose)
val clampedPose = fallback?.let { rescue -> evaluator.evaluate(preGlueModel, rescue.clampedDefaults) }
val drawables =
model.drawables.map { drawable ->
val mesh = drawable.mesh ?: return@map drawable
val worldPositions =
defaultPose.worldPositions[drawable.id]
?: clampedPose?.worldPositions?.get(drawable.id)
?: return@map drawable
if (worldPositions.size != mesh.positions.size) {
return@map drawable
}
// All-or-nothing: a size-mismatched delta array holds ABSOLUTE positions by the importer's
// fallback convention, so rebasing any prefix of it would double-count the base and mix two
// spaces in one array. A drawable carrying such a cell keeps its whole grid AND base
// untouched - partially rewriting either would corrupt what malformed data still encodes.
// Blend-shape forms are rest-relative like the grid cells, so they gate (and rebase) the
// same way - leaving them on the old base while the grid moves would shift every blend
// contribution by exactly (new base - old base).
val anyCellMismatches =
(drawable.geometryGrid?.cells?.any { cell -> cell.form.positionDeltas.size != mesh.positions.size } ?: false) ||
drawable.blendShapes.any { binding ->
binding.forms.any { form -> form != null && form.positionDeltas.size != mesh.positions.size }
}
if (anyCellMismatches) {
return@map drawable
}
// The eval negates Y into world space; canvas space is the pre-negation Y-down convention.
val canvasBase =
FloatArray(worldPositions.size) { coordIndex ->
if (coordIndex % 2 == 1) -worldPositions[coordIndex] else worldPositions[coordIndex]
}
// Only the geometry rebases - and since the split that is structural rather than something the
// copy has to remember: the channel tracks are a separate field and are simply not touched.
val rebasedGeometry =
drawable.geometryGrid?.let { grid ->
KeyformGrid(
grid.axes,
grid.cells.map { cell ->
val oldDeltas = cell.form.positionDeltas
KeyformCell(
cell.coordinate,
MeshDeltaForm(
FloatArray(oldDeltas.size) { coordIndex ->
(mesh.positions[coordIndex] + oldDeltas[coordIndex]) - canvasBase[coordIndex]
},
),
)
},
)
}
val rebasedBlendShapes =
drawable.blendShapes.map { binding ->
binding.copy(
forms =
binding.forms.map { form ->
form?.let { meshForm ->
MeshForm(
FloatArray(meshForm.positionDeltas.size) { coordIndex ->
(mesh.positions[coordIndex] + meshForm.positionDeltas[coordIndex]) - canvasBase[coordIndex]
},
meshForm.drawOrder,
meshForm.opacity,
meshForm.multiplyColor,
meshForm.screenColor,
)
}
},
)
}
drawable.copy(
mesh = DrawableMesh(canvasBase, mesh.uvs, mesh.indices),
geometryGrid = rebasedGeometry,
blendShapes = rebasedBlendShapes,
)
}
return model.copy(drawables = drawables)
}
/**
* The drawables the raw default pose hides, paired with the clamped pose that rescues them.
*
* @property Set<DrawableId> hiddenIds Drawables with a mesh but no default-pose geometry.
* @property Map<ParameterId, Float> clampedDefaults The pose to evaluate those drawables at.
*/
private class DefaultPoseFallback(
val hiddenIds: Set<DrawableId>,
val clampedDefaults: Map<ParameterId, Float>,
)
/**
* Which drawables need the clamped second-chance pose, and what that pose is.
*
* Both directions of the canvas-space conversion ask this, and they MUST agree: the forward pass maps
* such a drawable through the clamped pose, so an export that inverted it through the raw default
* would be undoing a transform that was never applied.
*
* No `keyforms != null` gate: an unkeyed drawable evaluates at its rest mesh rather than being skipped,
* so one still absent from the default pose is genuinely hidden (a hidden ancestor deformer) and
* deserves the same second chance as any other.
*
* @param PuppetModel model The model being converted.
* @param DeformedGeometry defaultPose Its evaluation at the raw default parameters.
* @return DefaultPoseFallback? The hidden set and their pose, or null when nothing is hidden.
*/
private fun defaultPoseFallbackFor(model: PuppetModel, defaultPose: DeformedGeometry): DefaultPoseFallback? {
val hiddenAtDefault =
model.drawables.filter { drawable ->
drawable.mesh != null && defaultPose.worldPositions[drawable.id] == null
}.map { drawable -> drawable.id }
if (hiddenAtDefault.isEmpty()) {
return null
}
return DefaultPoseFallback(hiddenAtDefault.toSet(), clampedDefaultsFor(model, hiddenAtDefault))
}
/**
* Lattice-UV band for an already-parent-local warp child. Wider than [0,1] so mild extrapolation
* (Bear TopTeeth reaches ~1.06) still counts as local; far tighter than canvas pixel rests, which
* sit in the hundreds or thousands after [restMeshesToCanvasSpace].
*/
private const val LATTICE_UV_MIN: Float = -1f
private const val LATTICE_UV_MAX: Float = 2f
/**
* The export's space seam for [puppet]: ensures an unkeyed drawable's rest mesh is parent-local for
* the MOC3 write.
*
* Two document origins store that rest differently:
* - After [restMeshesToCanvasSpace] (MOC3 import), the rest is canvas-space and must be inverted
* through the parent chain at the same pose the forward pass used.
* - UMA / CMO3 / warp-create remaps already author the rest in parent-local space (lattice UV under a
* warp). Blindly inverting those as if they were canvas double-transforms them - MouthCircle-class
* meshes crush to garbage coordinates and fly off when the parent warp opens.
*
* Under a warp, already-local rests are recognized by lying in the lattice-UV band; canvas rests fall
* well outside it and take the inverse. (A Newton round-trip cannot tell the two apart: an
* extrapolated preimage of a UV-as-canvas point still forward-maps to that point.) A drawable the
* chain cannot map returns null, which the export turns into a notice rather than a silently
* mis-scaled mesh.
*
* The pose is the neutral one for most drawables - the pose the rest mesh is defined at. A drawable
* the raw default hides went forward through the clamped second-chance pose instead, so it is inverted
* through that same clamped pose; using the raw default for it would undo a transform that was never
* applied.
*
* @param PuppetModel puppet The rig being exported.
* @return Function2 The seam: drawable id plus interleaved rest positions to parent-space positions,
* or null when the chain cannot invert.
*/
fun canvasToParentSpaceFor(puppet: PuppetModel): (DrawableId, FloatArray) -> FloatArray? {
// Resolved once per export rather than per drawable: the evaluation is the expensive part and the
// answer is a property of the model, not of whichever drawable is being written.
val preGlueModel = puppet.copy(glues = emptyList())
val defaultPose = CpuDeformationEvaluator().evaluate(preGlueModel, emptyMap())
val fallback = defaultPoseFallbackFor(puppet, defaultPose)
val drawableById = puppet.drawables.associateBy { drawable -> drawable.id }
val deformerById = puppet.deformers.associateBy { deformer -> deformer.id }
return space@{ drawableId, positions ->
val pose =
if (fallback != null && drawableId in fallback.hiddenIds) {
fallback.clampedDefaults
} else {
emptyMap()
}
// Warp children whose rest already sits in lattice UV must not be inverted - that is the
// MouthCircle double-transform. Detect before asking the chain so a UV rest never enters Newton
// as a fake canvas target.
val parent = drawableById[drawableId]?.parentDeformerId?.let { parentId -> deformerById[parentId] }
if (parent is Deformer.Warp && looksLikeLatticeUv(positions)) {
return@space positions
}
drawableSpaceMapping(puppet, pose, drawableId)?.let { mapping ->
// worldToLocal expects the renderer's Y-negated world space, and every vertex is solved.
val world = FloatArray(positions.size) { index -> if (index % 2 == 0) positions[index] else -positions[index] }
// The seed matters only for the warp inverse, and it must be a LATTICE UV, not a canvas
// coordinate: seeding Newton with the canvas-space value starts it hundreds of units outside
// the [0,1] lattice, where the damped step cannot walk back. The lattice center is the
// neutral seed - at most half a lattice away from any target, which the damped step covers.
val seed = FloatArray(positions.size) { LATTICE_CENTRE }
mapping.worldToLocal(world, seed, positions.indices.step(2).map { index -> index / 2 }.toSet())
}
}
}
/**
* Whether [positions] lie in the normalized lattice-UV band a warp child authors in parent-local
* space, as opposed to canvas-pixel rests from [restMeshesToCanvasSpace].
*
* @param FloatArray positions Interleaved rest coordinates.
* @return Boolean True when every coordinate is inside [[LATTICE_UV_MIN], [LATTICE_UV_MAX]].
*/
private fun looksLikeLatticeUv(positions: FloatArray): Boolean {
for (coordinate in positions) {
if (coordinate < LATTICE_UV_MIN || coordinate > LATTICE_UV_MAX) {
return false
}
}
return positions.isNotEmpty()
}
/**
* The clamped evaluation pose for drawables hidden at the raw default: every parameter driving a
* hidden drawable's own keyform grid or any grid on its ancestor deformer chain is coerced into the
* intersection of those axes' key ranges (the tightest span that satisfies every involved axis).
* When the intersection is empty (conflicting axes - pathological), the lower bound wins; unlisted
* parameters keep their defaults via the evaluator's fallback.
*
* @param PuppetModel model The imported model.
* @param List<DrawableId> hiddenIds The drawables absent from the raw default pose.
* @return Map<ParameterId, Float> The clamped values for the involved parameters only.
*/
private fun clampedDefaultsFor(model: PuppetModel, hiddenIds: List<DrawableId>): Map<ParameterId, Float> {
val drawableById = model.drawables.associateBy { it.id }
val deformerById = model.deformers.associateBy { it.id }
val lowerByParameter = HashMap<ParameterId, Float>()
val upperByParameter = HashMap<ParameterId, Float>()
fun addAxes(grid: KeyformGrid<*>?) {
for (axis in grid?.axes.orEmpty()) {
if (axis.keys.isEmpty()) {
continue
}
val firstKey = axis.keys.first()
val lastKey = axis.keys.last()
lowerByParameter[axis.parameterId] = max(lowerByParameter[axis.parameterId] ?: firstKey, firstKey)
upperByParameter[axis.parameterId] = min(upperByParameter[axis.parameterId] ?: lastKey, lastKey)
}
}
for (drawableId in hiddenIds) {
val drawable = drawableById[drawableId] ?: continue
addAxes(drawable.geometryGrid)
var parentId = drawable.parentDeformerId
var chainSteps = 0
while (parentId != null && chainSteps <= model.deformers.size) {
val deformer = deformerById[parentId] ?: break
// Geometry AND channel tracks: a deformer keyed only on, say, opacity still constrains which
// parameters have to be clamped for the second-chance default-pose evaluation.
when (deformer) {
is Deformer.Warp -> addAxes(deformer.geometryGrid)
is Deformer.Rotation -> addAxes(deformer.geometryGrid)
}
deformer.channelGrids.gridsByChannel.values.forEach { track: KeyformGrid<*> -> addAxes(track) }
parentId = deformer.parent
chainSteps++
}
}
val defaultByParameter = model.parameters.associate { parameter -> parameter.id to parameter.default }
return buildMap {
for ((parameterId, lowerBound) in lowerByParameter) {
val upperBound = upperByParameter[parameterId] ?: lowerBound
val defaultValue = defaultByParameter[parameterId] ?: 0f
val clampedValue = if (lowerBound <= upperBound) defaultValue.coerceIn(lowerBound, upperBound) else lowerBound
put(parameterId, clampedValue)
}
}
}
@@ -0,0 +1,169 @@
package org.umamo.render
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import org.umamo.runtime.model.PuppetModel
/**
* The texture data backing a puppet preview: the distinct atlas page(s) the art meshes sample, plus a
* per-drawable index into them. Art meshes typically share one atlas page in `TEXTURE_ATLAS` mode, but
* this structure generalises to multiple pages.
*
* For an IMPORTED document [atlases] is ordered by the renderer's own page walk and shares no
* numbering with the model's `PuppetAtlas.pages`. A page set Umamo generates itself (a repack's,
* built by `deriveAtlasTextures`) is index-parallel to `PuppetAtlas.pages` instead, so for generated
* sets a placement's page index is valid against both lists.
*
* [premultipliedAlpha] is the OR-fold of the CMO3 `GTexture2D.isPremultiplied` bits and is currently
* UNCONSUMED - and is deliberately kept that way. It is an editor texture-upload-convention flag
* (serialized true on nearly every model), NOT a claim that the decoded bytes are premultiplied: every
* ingested page is straight-alpha (PngCodec yields straight alpha; the fragment shader premultiplies
* in-shader with source factor GL_ONE), so wiring this to "unpremultiply the bytes" would over-darken
* the whole corpus. The version-dependent premultiplied-vs-straight COMPOSITING distinction (Cubism
* 5.2 and earlier plus the "(Before 5.3)" modes composite premultiplied; 5.3+ Color blend composites
* straight) is a separate axis, carried by `BlendMode.isLegacy` and handled in
* `BlendMath.compositeReference`, not by this field. See docs/format/CMO3.md, "Premultiplied vs
* straight alpha".
*
* @property List<DecodedImage> atlases The distinct decoded atlas pages.
* @property Map<String,Int> atlasIndexByDrawableId Drawable id (`ArtMesh…`) → index into [atlases].
* @property Boolean premultipliedAlpha Aggregated `GTexture2D.isPremultiplied`; unconsumed
* (see the note above) - do not drive rendering off it.
*/
class PuppetTextures(
val atlases: List<DecodedImage>,
val atlasIndexByDrawableId: Map<String, Int>,
val premultipliedAlpha: Boolean,
)
/**
* How [buildPuppetTextures] treats an atlas page whose bytes will not decode.
*
* The two ingest paths want opposite answers and each is right for its format, so the policy is the
* caller's to state rather than something the shared builder decides for them.
*/
enum class UndecodablePagePolicy {
/**
* Drop the page and unmap every drawable that sampled it; the build still succeeds. What a CMO3
* wants: its pixels are embedded in the model file, so a page that will not decode is one corrupt
* resource inside an otherwise editable rig, and refusing to open the document over it would cost
* the rigger everything else in the file. Those drawables render in fallback color.
*/
Skip,
/**
* Fail the whole build so the loader can report a broken import. What a MOC3 wants: its pages are
* sibling files named by model3.json, so one that will not decode means the family on disk is
* incomplete or mismatched - an import error to surface, not a puppet to render half of.
*/
Fail,
}
/**
* Builds the [PuppetTextures] for a puppet from its atlas page bytes and a per-drawable index into
* them - the format-agnostic core both ingest paths end at.
*
* Each format's own atlas-page walk (`cmo3AtlasPages`, `moc3AtlasPages`, in `:interop`) produces a
* neutral `AtlasPageSet` that the document loader unpacks into these two arguments and hands here, so
* the decode, the page-index validation, and the PuppetTextures shape are written once. Nothing about
* this function knows a format; it is deliberately reachable with hand-built arguments so tests need
* no corpus file.
*
* @param List<ByteArray> pageBytes The PNG bytes per atlas page, in index order.
* @param Map<String, Int> atlasIndexByDrawableId Drawable id (`ArtMesh…`) → index into [pageBytes].
* @param Boolean premultipliedAlpha Passed through to [PuppetTextures.premultipliedAlpha];
* see its docblock - aggregated by the CMO3 adapter
* and unconsumed, false everywhere else.
* @param UndecodablePagePolicy undecodablePage What an undecodable page costs.
* @return PuppetTextures? The decoded pages + index, or null when [undecodablePage] is
* [UndecodablePagePolicy.Fail] and a page failed to decode or a drawable's
* index fell outside [pageBytes]. Never null under
* [UndecodablePagePolicy.Skip].
*/
fun buildPuppetTextures(
pageBytes: List<ByteArray>,
atlasIndexByDrawableId: Map<String, Int>,
premultipliedAlpha: Boolean = false,
undecodablePage: UndecodablePagePolicy = UndecodablePagePolicy.Fail,
): PuppetTextures? {
val failOnBadPage = undecodablePage == UndecodablePagePolicy.Fail
// An index outside the page list must never reach the renderer: PuppetRenderer resolves pages by
// direct list indexing, so broken atlas wiring is caught here rather than crashing the render
// thread at first frame. Under Skip the same guard applies per drawable instead of per build -
// an unresolvable page number simply leaves that drawable out of the rebuilt map below.
if (failOnBadPage && atlasIndexByDrawableId.values.any { pageIndex -> pageIndex !in pageBytes.indices }) {
return null
}
// Skip can drop pages, which shifts every later page down by however many preceded it, so decoding
// records where each surviving page landed and the drawable map is rebuilt against that numbering.
// Under Fail nothing is ever dropped and the remap is an identity copy.
val atlases = ArrayList<DecodedImage>(pageBytes.size)
val keptIndexBySourceIndex = HashMap<Int, Int>(pageBytes.size)
for ((sourceIndex, bytes) in pageBytes.withIndex()) {
val image =
try {
PngCodec.read(bytes)
} catch (_: Exception) {
if (failOnBadPage) {
return null
}
continue
}
keptIndexBySourceIndex[sourceIndex] = atlases.size
atlases.add(DecodedImage(image.rgba, image.width, image.height))
}
val keptIndexByDrawableId = LinkedHashMap<String, Int>(atlasIndexByDrawableId.size)
for ((drawableId, sourceIndex) in atlasIndexByDrawableId) {
keptIndexBySourceIndex[sourceIndex]?.let { keptIndex -> keptIndexByDrawableId[drawableId] = keptIndex }
}
return PuppetTextures(atlases, keptIndexByDrawableId, premultipliedAlpha)
}
/**
* Re-encodes a decoded atlas page as PNG, for a page the document retains no source bytes for.
*
* The fallback half of both exports' page payload: a retained source PNG is written verbatim, which is
* faster and lossless, and this covers every page there is no such PNG for. A CMO3-origin document
* reaches it for every page (its pixels are embedded per drawable, so it retains no atlas PNGs at all).
* A MOC3-origin one retains a PNG per decoded page and so does not reach it, and falls back here only
* if those two lists ever diverge - which would otherwise leave that page with no bytes to write.
*
* Re-encoding rather than dropping the page is what keeps page INDICES stable - drawables address
* pages by number, so omitting one would renumber every page after it.
*
* @param DecodedImage atlas The decoded page.
* @return ByteArray The PNG bytes.
*/
fun encodeAtlasPng(atlas: DecodedImage): ByteArray =
PngCodec.write(RasterImage(width = atlas.width, height = atlas.height, rgba = atlas.rgba))
/**
* [puppet] with every drawable's atlas page taken from [textures].
*
* A MOC3 addresses its pages by index on the art mesh, so the export needs one on every drawable. A
* MOC3-origin document already carries them (the import reads them straight off the art mesh), but a
* CMO3 has no page index at all - its pixels are embedded per drawable - so those documents reach the
* export with every drawable still on the -1 sentinel, which the MOC3 lowering clamps to page 0,
* pointing a multi-page rig at one atlas. The decoded texture set is what knows the answer either
* way, so it is the one asked.
*
* @param PuppetModel puppet The rig being exported.
* @param PuppetTextures textures The document's decoded atlas set.
* @return PuppetModel The rig with its page bindings resolved, or [puppet] when none moved.
*/
fun withTexturePagesFrom(puppet: PuppetModel, textures: PuppetTextures): PuppetModel {
var moved = false
val drawables =
puppet.drawables.map { drawable ->
val page = textures.atlasIndexByDrawableId[drawable.id.raw] ?: return@map drawable
if (page == drawable.texturePage) {
drawable
} else {
moved = true
drawable.copy(texturePage = page)
}
}
return if (moved) puppet.copy(drawables = drawables) else puppet
}
@@ -0,0 +1,119 @@
package org.umamo.render
import org.umamo.format.png.PngCodec
import org.umamo.runtime.model.AtlasTileId
import kotlin.concurrent.Volatile
/**
* A document's source-art pixels, decoded on demand and keyed by atlas tile.
*
* Pixels only. Which tiles exist, how big they are, and where each one packs are model state
* (`PuppetModel.atlas`), because a repack authors them; this holds the one thing a model must not,
* since a raster in the model would ride along in every undo snapshot.
*
* Nothing is decoded until it is asked for: a CMO3 document loads synchronously on the UI thread, so
* decoding every tile up front would stall the open by seconds on a real model. A decoded tile is
* retained for the store's life, which is the document's life - a replaced document drops the store.
*
* Format-agnostic by construction: the decoder is injected. A CMO3 document supplies one over its
* retained graph's PNG bytes ([fromPng]); an artwork-origin document, whose reader already decoded
* every layer, supplies one over those rasters directly.
*
* @property Function decode Yields a tile's decoded pixels, or null when it has none or they will not
* decode. Called from any thread, possibly several at once, so it must share nothing mutable - and
* it must return the SAME instance for the same tile on every call when it can, because the
* renderer's texture cache and the viewport's freshness test compare decoded images by identity.
*/
class SourceArtRasters(
private val decode: (AtlasTileId) -> DecodedImage?,
) {
// A null value is a remembered failure (no bytes, or bytes that will not decode), which is why this
// is not a getOrPut - getOrPut treats a stored null as absent and would retry the decode every time.
private val decodedByTile = HashMap<AtlasTileId, DecodedImage?>()
// Rasters added after the store was built - artwork brought into an open document, the replacement
// tiles a reload mints - read before the injected decoder. An immutable map swapped whole behind a
// volatile reference, so the off-thread repack decode sees a complete map or the previous one,
// never a half-written one.
@Volatile
private var added: Map<AtlasTileId, DecodedImage> = emptyMap()
/**
* Adds already-decoded rasters for tiles the injected decoder knows nothing about - the layers of
* an artwork file added to the document after it opened, and the replacement tiles a reload,
* relink, or match mints over new art. Document-lifetime like the rest of the store: an added
* raster stays even if the edit that brought it is undone, which is harmless since its tile is then
* gone from the model. Re-adding a tile replaces its raster.
*
* @param Map rasters The decoded pixels by tile.
*/
fun addDecoded(rasters: Map<AtlasTileId, DecodedImage>) {
if (rasters.isEmpty()) {
return
}
added = added + rasters
}
/**
* A tile's pixels, decoding them on first request and caching the result (failures included).
*
* A raster added through [addDecoded] wins over the cache: a reload's replacement id (`<root>~<n>`)
* is minted past the ids the model holds NOW, so reload, undo, reload mints the same id twice with
* different pixels, and a cache entry taken between the two would otherwise stand in for the second.
* Both twins then hand out the added instance, which is what the identity comparisons need.
*
* CALLER-CONFINED: the cache is a plain map with no synchronization, so every call must come from
* the same thread (today, the UI thread). A second caller would not merely race the map - it could
* hand out a SECOND decoded instance for one tile, and both the renderer's texture cache and the
* viewport's freshness test compare decoded images by identity. Anything off that thread uses
* [decodeRaster] instead, which shares nothing.
*
* @param AtlasTileId tileId The tile to read.
* @return DecodedImage? The decoded raster, or null when the tile has no usable pixels.
*/
fun rasterFor(tileId: AtlasTileId): DecodedImage? {
added[tileId]?.let { raster -> return raster }
if (decodedByTile.containsKey(tileId)) {
return decodedByTile[tileId]
}
// The cached twin decodes through the uncached one: the two must produce the same image for the
// same bytes, because callers compare a cached result against a freshly decoded one by identity.
val decoded = decodeRaster(tileId)
decodedByTile[tileId] = decoded
return decoded
}
/**
* A tile's pixels, decoded fresh and cached nowhere - safe to call from any thread, including
* several at once.
*
* The uncached twin of [rasterFor], for callers that own their own result: the injected decoder
* shares nothing mutable, so nothing here is shared. Costs a repeat decode when a tile is already
* cached (for a store over encoded bytes), which is the price of not sharing a cache across threads.
*
* @param AtlasTileId tileId The tile to read.
* @return DecodedImage? The decoded raster, or null when the tile has no usable pixels.
*/
fun decodeRaster(tileId: AtlasTileId): DecodedImage? = added[tileId] ?: decode(tileId)
companion object {
/**
* A store over encoded PNG bytes - the CMO3 case, where every tile's pixels sit in the retained
* graph as an embedded PNG and decoding is deferred to first request.
*
* @param Function readBytes Yields a tile's PNG bytes, or null when it has none.
* @return SourceArtRasters The store; bytes that will not decode read as no raster.
*/
fun fromPng(readBytes: (AtlasTileId) -> ByteArray?): SourceArtRasters =
SourceArtRasters { tileId ->
readBytes(tileId)?.let { bytes ->
try {
val image = PngCodec.read(bytes)
DecodedImage(image.rgba, image.width, image.height)
} catch (_: Exception) {
null
}
}
}
}
}
@@ -0,0 +1,125 @@
package org.umamo.render
import org.umamo.render.device.RenderDevice
import org.umamo.render.device.RenderTarget
import org.umamo.render.device.RenderTargetSpec
import org.umamo.render.device.TextureFormat
import kotlin.math.max
/**
* The viewport's offscreen surface pair: a supersampled draw target the renderer draws into, and a
* display-size resolve target the draw is box-downscaled into for read-back.
*
* Backend-neutral - both targets and the resolve come from the [device], so every backend's viewport
* host shares this class instead of re-owning two framebuffers apiece. The draw target is write-only
* (`sampled = false`, a renderbuffer on GL); the resolve target is sampled so it can be read back.
*
* Allocation is GROW-ONLY: the targets are kept at a per-axis high-water capacity and each render
* uses only its bottom-left (render-origin) used region, resolved and read back at the used size.
* A gutter drag resizes the viewport every frame, and one surface is shared by every area, so
* differently-sized areas alternate sizes render-to-render - a recreate-on-any-change policy paid a
* framebuffer destroy + create per frame in both cases. The cost is that the session retains the
* high-water allocation (a 2x draw target at 4K is about 130 MB).
*
* All calls run on the render thread with the device's context current; this class never crosses
* threads.
*
* @property RenderDevice device The backend the targets live on.
* @property Int scale The maximum framebuffer pixels per display pixel (the full
* supersample factor). It bounds ensure's activeScale; capacity itself follows the high-water of
* the pixel sizes actually requested, so a session that never renders above 1x never pays a 2x
* allocation, and the first higher-scale render grows the targets once.
*
* @note Shrink-on-idle (trimming the high-water allocation after a quiet period) is the named
* future refinement if the retained memory ever matters in practice.
*/
class SupersampledSurface(
private val device: RenderDevice,
val scale: Int,
) {
private var draw: RenderTarget? = null
private var resolve: RenderTarget? = null
private var drawCapacityWidth = 0
private var drawCapacityHeight = 0
private var resolveCapacityWidth = 0
private var resolveCapacityHeight = 0
/** The display-pixel width of the most recent [ensure] - the used extent of both targets. */
var usedWidth: Int = 0
private set
/** The display-pixel height of the most recent [ensure] - the used extent of both targets. */
var usedHeight: Int = 0
private set
/** The supersample factor of the most recent [ensure] (1 up to [scale]). */
var usedScale: Int = scale
private set
/** The supersampled draw target (capacity-sized; render its used region). Call [ensure] first. */
val drawTarget: RenderTarget
get() = draw ?: error("ensure(width, height) before drawTarget")
/** The resolve target the read-back reads (capacity-sized; used region only). Call [ensure] first. */
val resolveTarget: RenderTarget
get() = resolve ?: error("ensure(width, height) before resolveTarget")
/**
* Ensures both targets can hold a [width] x [height] render (the draw target at [activeScale] x),
* growing a target only when a requested axis exceeds its capacity, and returns the draw target.
* Always records the used size and scale; a smaller or equal request never reallocates.
*
* @param Int width The display width in pixels.
* @param Int height The display height in pixels.
* @param Int activeScale The supersample factor for this render (defaults to the full [scale]).
* @return RenderTarget The supersampled draw target.
*/
fun ensure(width: Int, height: Int, activeScale: Int = scale): RenderTarget {
require(width > 0 && height > 0) { "surface size must be positive, got ${width}x$height" }
require(activeScale in 1..scale) { "activeScale must be in 1..$scale, got $activeScale" }
val drawWidth = width * activeScale
val drawHeight = height * activeScale
if (drawWidth > drawCapacityWidth || drawHeight > drawCapacityHeight) {
draw?.let { existing -> device.destroyRenderTarget(existing) }
drawCapacityWidth = max(drawWidth, drawCapacityWidth)
drawCapacityHeight = max(drawHeight, drawCapacityHeight)
draw =
device.createRenderTarget(
RenderTargetSpec(drawCapacityWidth, drawCapacityHeight, TextureFormat.Rgba8, sampled = false),
)
}
if (width > resolveCapacityWidth || height > resolveCapacityHeight) {
resolve?.let { existing -> device.destroyRenderTarget(existing) }
resolveCapacityWidth = max(width, resolveCapacityWidth)
resolveCapacityHeight = max(height, resolveCapacityHeight)
resolve =
device.createRenderTarget(
RenderTargetSpec(resolveCapacityWidth, resolveCapacityHeight, TextureFormat.Rgba8, sampled = true),
)
}
usedWidth = width
usedHeight = height
usedScale = activeScale
return drawTarget
}
/** Box-downscales the draw target's used region into the resolve target's used region. */
fun resolve() {
device.resolveUsed(drawTarget, usedWidth * usedScale, usedHeight * usedScale, resolveTarget, usedWidth, usedHeight)
}
/** Frees both targets and resets the capacities. Safe to call before the first [ensure] and idempotent. */
fun dispose() {
draw?.let { device.destroyRenderTarget(it) }
resolve?.let { device.destroyRenderTarget(it) }
draw = null
resolve = null
drawCapacityWidth = 0
drawCapacityHeight = 0
resolveCapacityWidth = 0
resolveCapacityHeight = 0
usedWidth = 0
usedHeight = 0
usedScale = scale
}
}
@@ -0,0 +1,183 @@
package org.umamo.render
import kotlin.math.roundToInt
/**
* The visible content extent in world space (the renderer's post-deform, Y-up pixel space). It frames
* the model for an initial fit; width and height are clamped by the producer to at least 1 so a
* degenerate model never divides by zero downstream.
*
* 内容の存在範囲(ワールド空間、ピクセル単位)。モデルの初期フレーミングに使う。
*
* @property Float minX Left edge in world units.
* @property Float minY Bottom edge in world units.
* @property Float width Extent along X in world units.
* @property Float height Extent along Y in world units.
*/
data class ContentBounds(val minX: Float, val minY: Float, val width: Float, val height: Float)
/**
* A 2D viewport camera over the puppet's world space: an orthographic pan/zoom, no rotation. The model
* renders 1:1 (one world unit = one model pixel = one screen pixel) at [zoom] == 1. Deformation never
* reframes the view - the camera is set once (fit on open) and thereafter moved only by the user.
*
* Every edit helper is PURE - it returns a new camera and touches no GL - so the navigation maths
* unit-tests without a context, the same discipline as the workspace splitter's pure ratio function.
* The render backend consumes only [worldToNdc].
*
* Coordinate conventions: screen pixels measure +x right, +y DOWN from the top-left; world space is
* +y UP (the deform shader flips Cubism's native +y-down before projection). The screen-to-world maths
* below therefore carries the Y sign explicitly.
*
* 2D ビューポートカメラ(平行投影のパン/ズーム、回転なし)。zoom==1 で 1 ワールド単位=1 画面ピクセル。
* 編集ヘルパは全て純粋関数(新しいカメラを返し GL に触れない)なので、操作の数学を文脈なしでテストできる。
*
* @property Float centerX World X shown at the viewport center.
* @property Float centerY World Y shown at the viewport center.
* @property Float zoom Screen pixels per world unit (1 == true 1:1).
*/
data class ViewportCamera(val centerX: Float, val centerY: Float, val zoom: Float) {
/**
* Builds the affine world-to-NDC parameters the vertex shader applies as
* `ndc = world * (scaleX, scaleY) + (transformX, transformY)`. A world point at the camera center
* maps to NDC origin (the viewport center); a point one unit to the right maps [zoom] pixels right.
*
* @param Int viewportWidth Target width in pixels.
* @param Int viewportHeight Target height in pixels.
* @return FloatArray [scaleX, scaleY, transformX, transformY].
*/
fun worldToNdc(viewportWidth: Int, viewportHeight: Int): FloatArray {
val scaleX = 2f * zoom / viewportWidth
val scaleY = 2f * zoom / viewportHeight
return floatArrayOf(scaleX, scaleY, -centerX * scaleX, -centerY * scaleY)
}
/**
* Pans by a screen-pixel drag delta in grab style - the world point under the pointer stays under
* the pointer. Y carries the screen-down vs world-up sign flip.
*
* @param Float deltaXpx Horizontal drag in pixels (+ right).
* @param Float deltaYpx Vertical drag in pixels (+ down).
* @return ViewportCamera The panned camera.
*/
fun panByScreen(deltaXpx: Float, deltaYpx: Float): ViewportCamera =
copy(centerX = centerX - deltaXpx / zoom, centerY = centerY + deltaYpx / zoom)
/**
* Cursor-anchored zoom by [deltaPercent] percentage points (the wheel zoom): the world point under
* the cursor stays pinned to that same pixel, and the result snaps to the [stepPercent] grid so clean
* values (… 100%, 50%, 25% …) are reachable instead of drifting off the fit-derived ratio. The recenter
* uses the snapped, clamped zoom so the pin holds exactly even at the limits.
*
* @param Float deltaPercent Percentage points to add (negative zooms out).
* @param Float stepPercent The grid the result snaps to (e.g. 1 or 5).
* @param Float cursorXpx Cursor X in pixels from the left.
* @param Float cursorYpx Cursor Y in pixels from the top.
* @param Int viewportWidth Viewport width in pixels.
* @param Int viewportHeight Viewport height in pixels.
* @return ViewportCamera The zoomed camera.
*/
fun zoomAtCursorByPercent(deltaPercent: Float, stepPercent: Float, cursorXpx: Float, cursorYpx: Float, viewportWidth: Int, viewportHeight: Int): ViewportCamera {
val newZoom = snappedZoom(deltaPercent, stepPercent)
val halfWidth = viewportWidth / 2f
val halfHeight = viewportHeight / 2f
val worldX = centerX + (cursorXpx - halfWidth) / zoom
val worldZ = centerY + (halfHeight - cursorYpx) / zoom
return ViewportCamera(
worldX - (cursorXpx - halfWidth) / newZoom,
worldZ - (halfHeight - cursorYpx) / newZoom,
newZoom,
)
}
/**
* Centerd zoom by [deltaPercent] percentage points (the keyboard zoom-in/out), snapping to the
* [stepPercent] grid and leaving the centerd world point fixed.
*
* @param Float deltaPercent Percentage points to add (negative zooms out).
* @param Float stepPercent The grid the result snaps to.
* @return ViewportCamera The zoomed camera.
*/
fun zoomedByPercent(deltaPercent: Float, stepPercent: Float): ViewportCamera = copy(zoom = snappedZoom(deltaPercent, stepPercent))
/**
* The zoom scale after adding [deltaPercent] points to the current zoom-percentage and snapping to the
* [stepPercent] grid, clamped to the limits. Snapping to the grid is what makes round percentages
* land exactly: from a 41.3% fit, +1%-steps pass through 42, 43, … 100, and +5%-steps through 45, 50, …
*
* @param Float deltaPercent Percentage points to add.
* @param Float stepPercent The grid to snap to.
* @return Float The new zoom scale (screen px per world unit).
*/
private fun snappedZoom(deltaPercent: Float, stepPercent: Float): Float {
val targetPercent = zoom * 100f + deltaPercent
val snappedPercent = (targetPercent / stepPercent).roundToInt() * stepPercent
return (snappedPercent / 100f).coerceIn(MIN_ZOOM, MAX_ZOOM)
}
/**
* Returns the camera at true 1:1 (zoom 1) about the current center - the "actual size" / 100% view.
*
* @return ViewportCamera The 1:1 camera.
*/
fun withActualSize(): ViewportCamera = copy(zoom = 1f)
/**
* Frames a screen-pixel rectangle (Blender's Zoom Region / Shift+B): the dragged box fills the viewport,
* centerd on the box center. The two corners may be given in any order. The scale uses min() so the
* WHOLE box fits inside the viewport (letterboxed on the looser axis) rather than cropping it; a degenerate
* (zero-area) box is guarded by a one-pixel floor, and the zoom is clamped to the limits so a tiny box
* cannot explode past MAX_ZOOM. Pure, so the framing maths unit-tests without a context.
*
* @param Float leftPx One horizontal box edge in screen pixels.
* @param Float topPx One vertical box edge in screen pixels.
* @param Float rightPx The other horizontal box edge in screen pixels.
* @param Float bottomPx The other vertical box edge in screen pixels.
* @param Int viewportWidth The viewport width in pixels.
* @param Int viewportHeight The viewport height in pixels.
* @return ViewportCamera The camera framing the box.
*/
fun framingScreenRect(leftPx: Float, topPx: Float, rightPx: Float, bottomPx: Float, viewportWidth: Int, viewportHeight: Int): ViewportCamera {
val minX = minOf(leftPx, rightPx)
val maxX = maxOf(leftPx, rightPx)
val minY = minOf(topPx, bottomPx)
val maxY = maxOf(topPx, bottomPx)
val rectWidth = (maxX - minX).coerceAtLeast(1f)
val rectHeight = (maxY - minY).coerceAtLeast(1f)
// min() so the whole box fits inside the viewport (letterboxed on the looser axis), never cropped.
val fitScale = minOf(viewportWidth / rectWidth, viewportHeight / rectHeight)
val newZoom = (zoom * fitScale).coerceIn(MIN_ZOOM, MAX_ZOOM)
val rectCenterXpx = (minX + maxX) / 2f
val rectCenterYpx = (minY + maxY) / 2f
// Unproject the box center through the CURRENT camera (screen->world; Y flips), the inverse of the
// same affine worldToNdc applies, so the box center lands at the viewport center under the new camera.
val worldCenterX = centerX + (rectCenterXpx - viewportWidth / 2f) / zoom
val worldCenterZ = centerY + (viewportHeight / 2f - rectCenterYpx) / zoom
return ViewportCamera(worldCenterX, worldCenterZ, newZoom)
}
companion object {
/** Hard zoom floor / ceiling, so a stray wheel spin can't lose or explode the model. */
const val MIN_ZOOM: Float = 0.02f
const val MAX_ZOOM: Float = 64f
/** Fraction of the viewport a fit leaves the content occupying, so it isn't edge-to-edge. */
const val FIT_MARGIN: Float = 0.9f
/**
* Frames [content] centerd in the viewport with a small margin - the default view on open and the
* target of the Fit command.
*
* @param ContentBounds content The extent to frame.
* @param Int viewportWidth Viewport width in pixels.
* @param Int viewportHeight Viewport height in pixels.
* @return ViewportCamera The fitted camera.
*/
fun fit(content: ContentBounds, viewportWidth: Int, viewportHeight: Int): ViewportCamera {
val zoom =
(FIT_MARGIN * minOf(viewportWidth.toFloat() / content.width, viewportHeight.toFloat() / content.height))
.coerceIn(MIN_ZOOM, MAX_ZOOM)
return ViewportCamera(content.minX + content.width / 2f, content.minY + content.height / 2f, zoom)
}
}
}
@@ -0,0 +1,214 @@
package org.umamo.render.device
import org.umamo.render.GridColors
import org.umamo.render.glsl.MAX_BLEND_CORNERS
import org.umamo.render.glsl.MAX_CORNERS
// The per-draw and per-pass shader inputs, as structs rather than named scalars.
//
// The renderer names no uniform. Each backend hand-writes one marshaller per struct: the GL family caches
// the locations once at pipeline creation and issues glUniform*; a Metal backend would write a mirroring
// MSL struct and setVertexBytes it. Deliberately NOT reflection-driven - kotlin-reflect does not exist on
// Kotlin/Native - and deliberately not a writeTo(sink), which would force this shared code to commit to a
// memory layout when std140 and MSL alignment disagree. commonMain supplies VALUES; layout is the
// backend's. That split is the cleanest line in the design.
/** The camera's world→NDC affine: `ndc = world * (scaleX, scaleY) + (offsetX, offsetY)`. */
public data class WorldToNdc(val scaleX: Float, val scaleY: Float, val offsetX: Float, val offsetY: Float)
/**
* One drawable's per-pose deform inputs: the active morph corners and the baked parent transform.
*
* MUTABLE AND REUSED. The renderer refills one instance per draw rather than allocating ~60 of these a
* frame. A device implementation MUST therefore marshal every field before returning and MUST NOT retain
* the instance. Both `glUniform*` and Metal's `setVertexBytes` copy, so both can honor that; a backend
* that wanted to record and replay a command buffer could not, and would need its own copy.
*
* Getting this wrong renders garbage that looks exactly like a driver bug, which is why it is stated here
* rather than left to be discovered.
*
* @property Int cornerCount Active corners, 0..MAX_CORNERS.
* @property IntArray cornerCell Each active corner's keyform cell linear index; length MAX_CORNERS.
* @property FloatArray cornerWeight Each active corner's blend weight; length MAX_CORNERS.
* @property Int parentType 0 = direct, 1 = rotation, 2 = warp.
* @property FloatArray rotation The rotation affine (c12,c13,c14,c15,ox,oy); read when parentType==1.
* @property Int warpColumns Warp lattice columns; read when parentType==2.
* @property Int warpRows Warp lattice rows; read when parentType==2.
* @property Boolean warpBilinear Bilinear vs triangle blend; read when parentType==2.
*/
public class DeformUniforms {
var cornerCount: Int = 0
val cornerCell: IntArray = IntArray(MAX_CORNERS)
val cornerWeight: FloatArray = FloatArray(MAX_CORNERS)
// Blend-shape delta columns (appended after the grid cells in the delta texture); zero-blend
// drawables keep blendCount == 0 so the shader loop never runs.
var blendCount: Int = 0
val blendCell: IntArray = IntArray(MAX_BLEND_CORNERS)
val blendWeight: FloatArray = FloatArray(MAX_BLEND_CORNERS)
var parentType: Int = 0
val rotation: FloatArray = FloatArray(6)
var warpColumns: Int = 0
var warpRows: Int = 0
var warpBilinear: Boolean = false
}
/**
* One draw's fragment inputs, shared by the puppet and atlas-page pipelines.
*
* Mutable and reused on the same contract as [DeformUniforms].
*
* @property Boolean useTexture Sample [DrawTextures.atlas] rather than the flat color below.
* @property Float colorRed Flat color red, used when [useTexture] is false.
* @property Float colorGreen Flat color green, used when [useTexture] is false.
* @property Float colorBlue Flat color blue, used when [useTexture] is false.
* @property Float colorAlpha Flat color alpha, used when [useTexture] is false.
* @property Float opacity The pose-blended opacity, multiplied into alpha.
* @property Boolean useMask Multiply alpha by the mask coverage.
* @property Boolean invertMask Use 1 - coverage instead.
* @property Float multiplyRed Per-drawable multiply-color red (identity 1), applied before premultiply.
* @property Float multiplyGreen Per-drawable multiply-color green (identity 1).
* @property Float multiplyBlue Per-drawable multiply-color blue (identity 1).
* @property Float screenRed Per-drawable screen-color red (identity 0).
* @property Float screenGreen Per-drawable screen-color green (identity 0).
* @property Float screenBlue Per-drawable screen-color blue (identity 0).
* @property Float highlight How far to tint toward the highlight color (0 = untinted).
* @property Float highlightRed Highlight tint red.
* @property Float highlightGreen Highlight tint green.
* @property Float highlightBlue Highlight tint blue.
* @property FloatArray uvAffine The 2x3 row-major affine (m00, m01, m02, m10, m11, m12) applied to the
* interpolated texture coordinate before sampling. Identity leaves the stored mapping alone; a
* drawable sampling its SOURCE ARTWORK instead of the packed atlas carries the transform between
* those two frames here, so the same stored coordinates address either image. Rides on the fragment
* uniforms deliberately: the glue draw path marshals only these, so a vertex-stage home would
* silently miss glue meshes.
*/
public class FragmentUniforms {
var useTexture: Boolean = false
var colorRed: Float = 0f
var colorGreen: Float = 0f
var colorBlue: Float = 0f
var colorAlpha: Float = 0f
var opacity: Float = 1f
var useMask: Boolean = false
var invertMask: Boolean = false
var multiplyRed: Float = 1f
var multiplyGreen: Float = 1f
var multiplyBlue: Float = 1f
var screenRed: Float = 0f
var screenGreen: Float = 0f
var screenBlue: Float = 0f
var highlight: Float = 0f
var highlightRed: Float = 0f
var highlightGreen: Float = 0f
var highlightBlue: Float = 0f
// Six floats reused in place, like every other value here - see the class contract. Identity, NOT
// zeroes: a zeroed affine collapses every coordinate onto one texel.
val uvAffine: FloatArray = floatArrayOf(1f, 0f, 0f, 0f, 1f, 0f)
}
/**
* The textures one draw samples. Null means the draw does not use that slot.
*
* Mutable and reused per draw on the same contract as [DeformUniforms] - the renderer refills one instance
* rather than allocating a bundle per drawable per frame; the device must read the fields before returning
* and must not retain the instance (binding a texture reads its handle synchronously, so both backends can).
*
* @property GpuTexture? atlas The art texture the draw samples - the packed atlas page, or the
* drawable's source artwork when the puppet displays from that - or null to draw the flat color.
* @property GpuTexture? maskCoverage The clip mask's coverage, or null when unmasked.
* @property GpuTexture? deltaTexture The mesh's morph delta table (deform draws only).
* @property GpuTexture? warpControlPoints The parent warp's baked control points, or null when the parent
* is not a warp.
*/
public class DrawTextures {
public var atlas: GpuTexture? = null
public var maskCoverage: GpuTexture? = null
public var deltaTexture: GpuTexture? = null
public var warpControlPoints: GpuTexture? = null
/** The rendered layer a [composite draw][CompositeUniforms] blends in. */
public var compositeLayer: GpuTexture? = null
/** The destination snapshot the composite blends against (a copy of the target so far). */
public var destinationSnapshot: GpuTexture? = null
}
/**
* One composite draw's inputs: which color/alpha blend to compute in-shader, the composite's
* pose-blended channels, and its optional clip-mask sampling.
*
* Mutable and reused on the same contract as [DeformUniforms]. The mode ints are the MOC3 packed
* encodings' halves (colorMode 0-17, alphaMode 0-4 - see BlendModeMapping); the composite shader
* switches on them, and the pure reference `compositeReference` documents the exact math.
*
* @property Int colorMode The color blend mode int (0-17).
* @property Int alphaMode The alpha blend mode int (0-4).
* @property Float opacity The composite opacity (0..1), applied to the layer before blending.
* @property Float multiplyRed Multiply color red (identity 1).
* @property Float multiplyGreen Multiply color green (identity 1).
* @property Float multiplyBlue Multiply color blue (identity 1).
* @property Float screenRed Screen color red (identity 0).
* @property Float screenGreen Screen color green (identity 0).
* @property Float screenBlue Screen color blue (identity 0).
* @property Boolean useMask Multiply the layer's alpha by the mask coverage.
* @property Boolean invertMask Use 1 - coverage instead.
*/
public class CompositeUniforms {
public var colorMode: Int = 0
public var alphaMode: Int = 0
public var opacity: Float = 1f
public var multiplyRed: Float = 1f
public var multiplyGreen: Float = 1f
public var multiplyBlue: Float = 1f
public var screenRed: Float = 0f
public var screenGreen: Float = 0f
public var screenBlue: Float = 0f
public var useMask: Boolean = false
public var invertMask: Boolean = false
}
/**
* The grid backdrop's inputs for one pass.
*
* @property WorldToNdc worldToNdc The affine the fragment inverts to recover its world position.
* @property Int viewportWidth The framebuffer width, for the fragment's screen-to-world math.
* @property Int viewportHeight The framebuffer height.
* @property Float originX World x the lattice is anchored on (a major line crosses it).
* @property Float originY World y the lattice is anchored on.
* @property Float majorSpacingX Major line spacing along X, in world units.
* @property Float majorSpacingY Major line spacing along Y, in world units.
* @property Int subdivisions Minor lines per major cell.
* @property Float lineWidthPx Line half-width in framebuffer pixels (accounts for supersampling).
* @property GridColors colors The background / major / minor colors.
*/
public data class GridUniforms(
val worldToNdc: WorldToNdc,
val viewportWidth: Int,
val viewportHeight: Int,
val originX: Float,
val originY: Float,
val majorSpacingX: Float,
val majorSpacingY: Float,
val subdivisions: Int,
val lineWidthPx: Float,
val colors: GridColors,
)
/**
* One axis line's inputs.
*
* @property Float linePositionNdc The line's fixed coordinate, in NDC.
* @property Boolean vertical True for the vertical axis, false for the horizontal one.
* @property Float red Line red.
* @property Float green Line green.
* @property Float blue Line blue.
*/
public data class AxisLineUniforms(
val linePositionNdc: Float,
val vertical: Boolean,
val red: Float,
val green: Float,
val blue: Float,
)
@@ -0,0 +1,190 @@
package org.umamo.render.device
import org.umamo.render.puppet.GlueVertexAttributes
// The device's opaque handles and the specs used to create them.
//
// Handles are interfaces with no members on purpose: a caller can hold one and hand it back, and can do
// nothing else with it. The concrete type is backend state - a GL name, an MTLBuffer - and keeping it
// unreachable is what stops backend concepts leaking into the shared renderer.
/** A texture the device owns, sampleable from a shader. */
public interface GpuTexture
/**
* One mesh's vertex + index residency: rest positions, UVs, indices, and - for a glue mesh - the
* per-vertex weld attributes. Whatever the backend needs to issue one indexed draw of it.
*/
public interface GpuMesh
/** A compiled, immutable draw pipeline: shader stages, blend, and attribute layout, fixed at creation. */
public interface RenderPipeline
/** A compiled pipeline that evaluates the deform per vertex and writes positions, drawing nothing. */
public interface DeformCapturePipeline
/**
* A surface a pass renders into.
*
* Never implicitly current: every pass names the target it writes. The renderer used to discover its own
* target by reading the bound framebuffer out of ambient GL state, which worked only because the caller
* happened to have bound it first - a coupling that was invisible at both ends.
*/
public interface RenderTarget {
/** This target's contents as a sampleable texture, or null when created with `sampled = false`. */
val sampledTexture: GpuTexture?
}
/**
* The shared store of pass-1 deformed world positions, addressed by GLOBAL vertex index across every
* glue-involved mesh (see `org.umamo.render.puppet.planGlueLayout`).
*
* How the GPU actually holds it is the backend's business - a texture buffer on desktop GL today, and a
* 2D texture once the GLES 3.0 path lands, since texture buffers are 3.2 there. The renderer only ever
* says "the store", which is why that change does not reach it.
*/
public interface DeformedPositionStore
/** A texture/target pixel format. Only the two the renderer actually uses. */
public enum class TextureFormat {
/** 8-bit RGBA: atlases, mask coverage, and any target read back to the host. */
Rgba8,
/** 32-bit float RG: per-vertex morph deltas, warp control points, deformed positions. */
Rg32F,
}
/** How a texture's texels are filtered between sample points. */
public enum class TextureFilter {
/** No interpolation. Correct for data textures, where a blend between texels is meaningless. */
Nearest,
/** Bilinear. Correct for art. */
Linear,
}
/** What a texture yields for a coordinate outside [0, 1]. */
public enum class TextureWrap {
/** Repeats the nearest edge texel outward. Correct for an atlas page, whose art never reaches its border. */
ClampToEdge,
/**
* Yields transparent black outside the image. Correct for art sampled in its OWN frame, which a mesh
* routinely overhangs: an art mesh rings outside the opaque region and authored meshes extend further
* still for deformation coverage, so a drawable's coordinates run past its layer image by tens to
* hundreds of pixels. Clamping to the edge would repeat the border row or column across that overhang
* as a streak; transparent black reproduces what the packed atlas showed there, which is its padding.
* Atlas pages take it too: a document's page can be a single model image, with no padding at all.
*
* @note GL_CLAMP_TO_BORDER with a zero border color on the GL family (core in GL 3.3 and GLES 3.2),
* MTLSamplerAddressMode.clampToZero on Metal.
*/
ClampToTransparentBorder,
}
/**
* Which draw a pipeline performs.
*
* The device is asked for a pipeline by PURPOSE, never by shader source, so each backend owns its own
* shader library: the GL family reads `org.umamo.render.glsl`, and a Metal backend would supply MSL from
* a precompiled library. A `source(purpose, stage): String` seam was considered and rejected for
* assuming source text exists at runtime, which is false for a `.metallib`.
*
* Closed on purpose: adding a pipeline forces every backend to answer for it rather than silently
* lacking one.
*/
public enum class PipelinePurpose {
/** A non-glue art mesh: deform in the vertex stage, project, sample the atlas. */
PuppetDeformDraw,
/** A glue art mesh: read pass-1 own/partner positions, weld, project, sample the atlas. */
PuppetGlueDraw,
/** The UV editor's flat atlas-page underlay quad (attribute-less; corners from the vertex index). */
AtlasPageDraw,
/** The world-aligned grid backdrop (attribute-less full-screen triangle). */
GridBackdrop,
/** One world-origin axis line (attribute-less; two endpoints from the vertex index). */
WorldAxisLine,
/**
* The layer composite: an attribute-less full-screen triangle whose fragment blends a
* rendered layer against a destination snapshot in-shader (the 18 color x 5 alpha modes are not
* fixed-function-expressible), writing with blending DISABLED. Pair with [PipelineBlend.Opaque].
*/
Composite,
}
/**
* How a pipeline's fragments combine with the target.
*
* Semantic rather than factor-level: only these four combinations exist, they are model concepts, and a
* 15-factor x 4-slot surface would be API nobody uses that every backend would still have to map. An
* exhaustive `when` over four values also means adding a mode cannot be forgotten in a backend.
*
* [Opaque] is not one of `org.umamo.runtime.model.BlendMode`'s three - it is the backdrop's
* blending-disabled write, which is why this is its own enum rather than a reuse of that one.
*/
public enum class PipelineBlend {
/** Blending off: the fragment replaces the target. The grid and axis backdrop. */
Opaque,
/** Premultiplied source-over. The default for art. */
Normal,
/** Additive. Glows and highlights. */
Additive,
/** Multiply. Shadows and shading. */
Multiply,
}
/**
* The immutable description of a draw pipeline. Created once at init and reused every frame.
*
* @property PipelinePurpose purpose Which draw this pipeline performs.
* @property PipelineBlend blend How its fragments combine with the target.
* @property Boolean cullBackFaces Whether back faces are culled (the Cubism drawable
* Culling toggle); false = double-sided, the default. Part of the spec (not a draw parameter)
* so the state is bound with the pipeline, like blend.
*/
public data class RenderPipelineSpec(
val purpose: PipelinePurpose,
val blend: PipelineBlend,
val cullBackFaces: Boolean = false,
)
/**
* A render target to allocate.
*
* @property Int width Width in pixels.
* @property Int height Height in pixels.
* @property TextureFormat format The pixel format.
* @property Boolean sampled Whether a later pass samples this target as a texture. False lets a
* backend pick a write-only surface - the GL device allocates a renderbuffer rather than a texture,
* which cannot be read back directly but is otherwise cheaper.
*/
public data class RenderTargetSpec(
val width: Int,
val height: Int,
val format: TextureFormat,
val sampled: Boolean,
)
/**
* A mesh's static residency to upload.
*
* @property FloatArray restPositions Rest positions, interleaved x,y.
* @property FloatArray uvs Atlas UVs, interleaved u,v.
* @property IntArray indices Triangle indices. EMPTY IS LEGAL: a zero-triangle glue
* anchor draws nothing and exists only so its deformed positions can be a weld partner.
* @property GlueVertexAttributes? glueAttributes Per-vertex weld attributes, or null for a non-glue mesh.
*/
public class MeshSpec(
val restPositions: FloatArray,
val uvs: FloatArray,
val indices: IntArray,
val glueAttributes: GlueVertexAttributes?,
)
@@ -0,0 +1,556 @@
package org.umamo.render.device
import org.umamo.format.raster.RasterImage
/**
* The GPU backend seam: one implementation per graphics API.
*
* Everything above it - the puppet renderer, the deform eval, the pose resolution, the model diff - is
* backend-neutral. Desktop OpenGL 3.3 core is implemented; Android GLES 3.0 is a near-transliteration of
* it (the two differ in binding style, not semantics); iPadOS Metal is a later port.
*
* Shaped for the GL family first, deliberately. Where avoiding a GL-ism costs nothing it is avoided -
* passes name their target, pipelines are immutable, uniforms are structs - because those read better
* regardless. Where pre-solving Metal would cost real complexity for a backend that does not exist yet,
* it is not done; that bill is paid if and when Metal asks for it.
*
* A device is created by the host, which owns whatever context or queue the backend needs, and is used
* from ONE thread only - the render thread.
*
* Two kinds of work sit on this interface. Drawing is RECORDED into a frame: [beginFrame] hands out a
* [FrameEncoder] whose passes must all be begun and ended within one begin/end. The remaining
* operations - [resolve], [beginReadback] / [pollReadback], [readPixels], and every resource create /
* destroy - are SELF-CONTAINED: each is a complete unit of work on its own, called outside any frame, and
* a backend that records into command buffers (Metal) is free to open and commit its own buffer internally
* to service one. They are not part of a FrameEncoder because they do not compose with a pass - a resolve
* runs between a render frame and its read-back, and a read-back is polled across many later frames.
*
* GPU バックエンドの継ぎ目。GL / GLES / Metal ごとに実装する。描画はフレームに記録し、resolve / 読み戻し /
* リソース操作はフレーム外の自己完結操作。
*/
public interface RenderDevice {
// --- Resources. Everything the device hands out, the device frees. ---
/**
* Uploads an image as a sampleable texture.
*
* @param Int width Width in pixels.
* @param Int height Height in pixels.
* @param TextureFormat format The pixel format.
* @param TextureFilter filter How texels are filtered between sample points.
* @param ByteArray? pixels RGBA8888, top row first; null allocates without uploading.
* @param TextureWrap wrap What a coordinate outside [0, 1] yields.
* @return GpuTexture The texture.
*/
fun createTexture(
width: Int,
height: Int,
format: TextureFormat,
filter: TextureFilter,
pixels: ByteArray?,
wrap: TextureWrap = TextureWrap.ClampToEdge,
): GpuTexture
/**
* Uploads float texels (RG pairs, row-major from the top) as a sampleable texture.
*
* @param Int width Width in texels.
* @param Int height Height in texels.
* @param TextureFilter filter How texels are filtered.
* @param FloatArray texels The texels.
* @return GpuTexture The texture.
*/
fun createFloatTexture(width: Int, height: Int, filter: TextureFilter, texels: FloatArray): GpuTexture
/**
* Re-specifies an existing float texture's contents in place, keeping the same handle.
*
* The renderer calls this once per POSE CHANGE, never in the draw loop, and a backend must not
* re-create the resource here. Warp control points are pose-dependent but frame-invariant, and
* re-specifying that texture 60x/sec churned the d3d12/Mesa driver into progressively corrupting the
* points it sampled - the "facial features warp over time" bug, worst on masked warp meshes, which
* draw twice. The frequency is the fix; keep it.
*
* @param GpuTexture texture The texture to overwrite.
* @param Int width Width in texels.
* @param Int height Height in texels.
* @param FloatArray texels The new texels.
*/
fun updateFloatTexture(texture: GpuTexture, width: Int, height: Int, texels: FloatArray)
/**
* Uploads a mesh's static residency.
*
* @param MeshSpec spec The mesh's rest geometry and, for a glue mesh, its weld attributes.
* @return GpuMesh The resident mesh.
*/
fun createMesh(spec: MeshSpec): GpuMesh
/**
* Re-uploads a resident mesh's rest positions in place; the topology is unchanged.
*
* @param GpuMesh mesh The resident mesh.
* @param FloatArray restPositions The new positions, same length as at upload.
*/
fun updateMeshPositions(mesh: GpuMesh, restPositions: FloatArray)
/**
* Re-uploads a resident mesh's UVs in place; the topology is unchanged.
*
* @param GpuMesh mesh The resident mesh.
* @param FloatArray uvs The new UVs, same length as at upload.
*/
fun updateMeshUvs(mesh: GpuMesh, uvs: FloatArray)
/**
* Allocates a render target.
*
* @param RenderTargetSpec spec What to allocate.
* @return RenderTarget The target.
*/
fun createRenderTarget(spec: RenderTargetSpec): RenderTarget
/**
* Allocates the shared pass-1 deformed-position store.
*
* @param Int vertexCapacity The total glue vertex count across every glue mesh.
* @return DeformedPositionStore The store.
*/
fun createDeformedPositionStore(vertexCapacity: Int): DeformedPositionStore
/**
* Returns the draw pipeline for [spec], creating it on first ask. Pipelines are immutable and reused.
*
* @param RenderPipelineSpec spec Which draw, and how it blends.
* @return RenderPipeline The pipeline.
*/
fun createRenderPipeline(spec: RenderPipelineSpec): RenderPipeline
/**
* Returns the pipeline that evaluates the deform per vertex and writes positions without drawing.
*
* @return DeformCapturePipeline The pipeline.
*/
fun createDeformCapturePipeline(): DeformCapturePipeline
/** Frees [texture]. */
fun destroyTexture(texture: GpuTexture)
/** Frees [mesh] and every buffer it owns. */
fun destroyMesh(mesh: GpuMesh)
/** Frees [target]. */
fun destroyRenderTarget(target: RenderTarget)
// --- Frame recording ---
/**
* Begins recording a frame's work. End it with [FrameEncoder.endFrame].
*
* @return FrameEncoder The encoder.
*/
fun beginFrame(): FrameEncoder
/**
* Copies [source] into [destination], filtered - the supersample resolve (a box downscale when the
* source is larger).
*
* A device primitive rather than a caller-side blit, because "blit" is the GL spelling only:
* `glBlitFramebuffer` with GL_LINEAR does this in one call, but Metal's `MTLBlitCommandEncoder`
* can neither filter nor scale - a Metal backend implements this as a full-screen textured draw
* (or MPSImageBilinearScale). Exposing the honest verb keeps that difference inside the device.
*
* The layer-composite path also calls this BETWEEN two passes of one frame (snapshotting the
* destination before a composite draw samples it). On GL that is naturally ordered; a
* command-buffer backend must order the copy against the passes recorded before and after it.
*
* @param RenderTarget source The surface to read (any size).
* @param RenderTarget destination The surface to fill, at its own size.
* @param ScissorRect? region The sub-rectangle to copy (same coordinates in both surfaces),
* or null for the whole surface. Only valid when [source] and [destination] are the same size -
* the scaled supersample resolve always passes null. The composite path passes its layer bounds
* here so the destination snapshot copies only the pixels the scissored composite will sample.
* Equivalent to [resolveUsed] at the targets' full allocated sizes.
*/
fun resolve(source: RenderTarget, destination: RenderTarget, region: ScissorRect? = null)
/**
* [resolve] restricted to each target's USED region - the (width x height) extent the last pass
* actually rendered, anchored at the render origin (the GL device's bottom-left rows; a
* top-left-origin backend's top-left rows). This is the primitive a grow-only surface needs:
* its targets are allocated at a high-water capacity and only the used region holds pixels, so a
* full-allocation copy would read garbage and a full-allocation scale would misplace the content.
*
* @param RenderTarget source The surface to read.
* @param Int sourceUsedWidth The rendered extent of [source] along x, in pixels.
* @param Int sourceUsedHeight The rendered extent of [source] along y, in pixels.
* @param RenderTarget destination The surface to fill.
* @param Int destinationUsedWidth The rendered extent of [destination] along x, in pixels.
* @param Int destinationUsedHeight The rendered extent of [destination] along y, in pixels.
* @param ScissorRect? region The sub-rectangle to copy (same top-left-origin coordinates in both
* used regions, flipped against the USED height on a bottom-up backend), or null to scale the
* whole source used region onto the destination used region (filtered - the supersample
* resolve). Only valid when the used sizes are equal, exactly like [resolve]'s same-size rule.
*/
fun resolveUsed(
source: RenderTarget,
sourceUsedWidth: Int,
sourceUsedHeight: Int,
destination: RenderTarget,
destinationUsedWidth: Int,
destinationUsedHeight: Int,
region: ScissorRect? = null,
)
// --- Read-back ---
/**
* Begins an ASYNCHRONOUS read-back of [target], returning immediately.
*
* The synchronous [readPixels] stalls the pipeline until the GPU finishes; this schedules the copy
* on the GPU timeline instead, so a per-frame caller (the viewport read-back) never blocks while a
* slider is dragged. Poll the ticket with [pollReadback] on later ticks.
*
* The GL device implements this as glReadPixels into a pooled pixel-buffer object gated by a fence;
* a Metal backend would stash the bytes from a command-buffer completion handler and hand them over
* on the poll - polling (rather than a callback) is deliberate, so results always arrive on the
* render thread on every backend, whatever thread the backend completes on.
*
* @param RenderTarget target The target to read.
* @return ReadbackTicket The claim ticket to poll.
*/
fun beginReadback(target: RenderTarget): ReadbackTicket
/**
* [beginReadback] restricted to the target's USED region (see [resolveUsed] for the anchoring
* contract). The delivered image is usedWidth x usedHeight, top row first as always.
*
* @param RenderTarget target The target to read.
* @param Int usedWidth The rendered extent along x, in pixels.
* @param Int usedHeight The rendered extent along y, in pixels.
* @return ReadbackTicket The claim ticket to poll.
*/
fun beginReadback(target: RenderTarget, usedWidth: Int, usedHeight: Int): ReadbackTicket
/**
* The pixels of an in-flight read-back once ready, or null while the GPU is still copying.
*
* Non-blocking, and null means STILL IN FLIGHT and nothing else: once the copy is done the ticket is
* spent and this returns a non-null image, EVEN if the backend then hit an error retrieving the bytes
* (in which case the image is a same-size zero fill - one lost frame, never a null the caller would
* mistake for still-in-flight and re-poll into the spent-ticket check). One-shot: the first non-null
* return spends the ticket and recycles its staging; polling a spent ticket is a caller bug. Same
* orientation contract as [readPixels]: RGBA8888, TOP row first, whatever the backend's framebuffer
* origin.
*
* @param ReadbackTicket ticket The claim ticket from [beginReadback].
* @return RasterImage? The pixels once ready, or null while still in flight.
*/
fun pollReadback(ticket: ReadbackTicket): RasterImage?
/**
* Abandons an in-flight read-back, freeing its staging without waiting for the pixels. For
* teardown; a spent ticket is a no-op.
*
* @param ReadbackTicket ticket The claim ticket to abandon.
*/
fun cancelReadback(ticket: ReadbackTicket)
/**
* Reads [target] back to the host, synchronously.
*
* Always RGBA8888 with the TOP row first, whatever the backend's framebuffer origin: the GL device
* flips its bottom-up read, and a top-left-origin backend would not. Fixing the convention here is
* what stops every caller having to ask which way up a backend is.
*
* Synchronous, so it stalls the pipeline. Fine for verification and thumbnails; the per-frame path
* uses an asynchronous read-back instead.
*
* @param RenderTarget target The target to read.
* @return RasterImage The pixels, top row first.
*/
fun readPixels(target: RenderTarget): RasterImage
/**
* [readPixels] restricted to the target's USED region (see [resolveUsed] for the anchoring
* contract). The returned image is usedWidth x usedHeight, top row first.
*
* @param RenderTarget target The target to read.
* @param Int usedWidth The rendered extent along x, in pixels.
* @param Int usedHeight The rendered extent along y, in pixels.
* @return RasterImage The pixels, top row first.
*/
fun readPixels(target: RenderTarget, usedWidth: Int, usedHeight: Int): RasterImage
/**
* The largest render target edge this device can allocate AND draw to, in pixels.
*
* The smallest of the limits a render target meets on its way through a frame: the texture size, the
* renderbuffer size, and the viewport size. A caller rendering something larger than this splits it
* into tiles rather than asking the device for a target it cannot make.
*
* @return Int The edge, in pixels.
*/
fun maxRenderTargetSize(): Int
/**
* The backend's device / driver / version as one line - a startup diagnostic confirming which backend
* actually drives the viewport (a hardware driver vs a software rasterizer, say).
*
* @return String The description.
*/
fun describeBackend(): String
}
/**
* An in-flight asynchronous read-back - an opaque claim ticket for [RenderDevice.pollReadback].
*
* One-shot: a ticket yields its pixels exactly once, after which it is spent and the backend has
* recycled its staging.
*/
public interface ReadbackTicket
/**
* One frame's recorded work. Passes run in the order they are begun.
*
* A pass that reads what an earlier pass wrote must be separated from it by [barrier].
*/
public interface FrameEncoder {
/**
* Begins a render pass. End it before beginning another - passes do not nest.
*
* @param RenderPassSpec spec The target, what to do with its existing contents, and the viewport.
* @return RenderPassEncoder The pass encoder.
*/
fun beginRenderPass(spec: RenderPassSpec): RenderPassEncoder
/**
* Begins the deform-capture pass (glue pass 1).
*
* @param DeformCapturePipeline pipeline The capture pipeline.
* @param DeformedPositionStore store Where the deformed positions land.
* @return DeformCapturePassEncoder The pass encoder.
*/
fun beginDeformCapturePass(pipeline: DeformCapturePipeline, store: DeformedPositionStore): DeformCapturePassEncoder
/**
* Declares that work after this point reads [store] as written by work before it, so the backend
* orders the write against the read.
*
* A declared DEPENDENCY, not an instruction to stall - which is what lets each backend meet it its own
* way. The GL device issues `glFinish`: the WSL d3d12/Mesa stack does not reliably order transform
* feedback's writes before a later texture read, so pass 2 sampled a half-written store and produced
* garbage welds while a parameter moved. `glMemoryBarrier` cannot help - feedback writes are
* coherent-pipeline writes, outside its scope - so the full sync is the honest fix. A Metal backend
* would implement this as a genuine no-op, since it tracks the dependency itself within a command
* buffer; that is correct, not a stub.
*
* The renderer calls it only on pose-change frames, so a static pose pays nothing.
*
* @param DeformedPositionStore store The store written before and read after.
*/
fun barrier(store: DeformedPositionStore)
/** Submits the frame. */
fun endFrame()
}
/**
* What a render pass does with its target's existing contents on entry.
*
* GL needs none of this and ignores it; it is stated because a tile-based GPU cannot infer it, and
* because it is genuinely free information the renderer already has. The grid is an opaque full-screen
* fill that both clears and paints, so its pass is [DontCare] - and on a tile-based GPU that means the
* tile is never fetched at all.
*/
public enum class LoadAction {
/** Discard and fill with the clear color. */
Clear,
/** Preserve: the pass reads what was already there. */
Load,
/** The pass overwrites every pixel, so the previous contents need not be fetched. */
DontCare,
}
/** Whether a pass's results are kept. [DontCare] lets a tile-based GPU skip the write-back. */
public enum class StoreAction {
/** Keep the results. */
Store,
/** Discard them. */
DontCare,
}
/**
* An axis-aligned pixel rectangle restricting where a pass (or a region resolve) writes.
*
* Coordinates follow the read-back convention: (0, 0) is the TOP-LEFT pixel, whatever the backend's
* framebuffer origin (the GL device converts to its bottom-left origin internally). Fixing the
* convention here is what stops every caller having to ask which way up a backend is.
*
* @property Int x Left edge in pixels.
* @property Int y Top edge in pixels.
* @property Int width Width in pixels (> 0).
* @property Int height Height in pixels (> 0).
*/
public data class ScissorRect(
val x: Int,
val y: Int,
val width: Int,
val height: Int,
)
/**
* One render pass.
*
* Every field is explicit because a pass that discovered its own target could not exist on a backend with
* no bound-framebuffer concept - and because, even on GL, discovering it from ambient state hid a real
* coupling between the renderer and whoever bound the framebuffer first.
*
* @property RenderTarget colorTarget The surface this pass writes.
* @property LoadAction loadAction What to do with its existing contents on entry.
* @property StoreAction storeAction Whether to keep the results.
* @property Float clearRed Clear red; read only when [loadAction] is [LoadAction.Clear].
* @property Float clearGreen Clear green; read only when [loadAction] is [LoadAction.Clear].
* @property Float clearBlue Clear blue; read only when [loadAction] is [LoadAction.Clear].
* @property Float clearAlpha Clear alpha; read only when [loadAction] is [LoadAction.Clear].
* @property Int viewportWidth The viewport width in pixels.
* @property Int viewportHeight The viewport height in pixels.
* @property ScissorRect? scissor Restricts every write of the pass - the clear included - to the
* rectangle, for the whole pass (per-pass fixed state, like the target). Null writes everywhere.
* The composite path uses this to confine a layer's clear + composite to the subtree's bounds.
*/
public data class RenderPassSpec(
val colorTarget: RenderTarget,
val loadAction: LoadAction,
val viewportWidth: Int,
val viewportHeight: Int,
val storeAction: StoreAction = StoreAction.Store,
val clearRed: Float = 0f,
val clearGreen: Float = 0f,
val clearBlue: Float = 0f,
val clearAlpha: Float = 0f,
val scissor: ScissorRect? = null,
)
/** Records draws into one render pass. */
public interface RenderPassEncoder {
/**
* Binds the pipeline subsequent draws use. Blend and shader stages are fixed by it.
*
* @param RenderPipeline pipeline The pipeline.
*/
fun setPipeline(pipeline: RenderPipeline)
/**
* Sets the pass-wide world→NDC affine and the screen-space texture divisor.
*
* The divisor is the ALLOCATED size of the screen-space side textures (mask coverage, composite
* layer, destination snapshot) a draw may sample by `gl_FragCoord / screenTexSize` - never the
* pass viewport, which lives in [RenderPassSpec]. The two agree only when the side targets are
* exactly viewport-sized; with grow-only side targets the divisor is the high-water capacity.
*
* @param WorldToNdc worldToNdc The camera affine.
* @param Int screenTexWidth The sampled side textures' allocated width, in pixels.
* @param Int screenTexHeight The sampled side textures' allocated height, in pixels.
*/
fun setCamera(worldToNdc: WorldToNdc, screenTexWidth: Int, screenTexHeight: Int)
/**
* Draws one deforming art mesh.
*
* @param GpuMesh mesh The mesh.
* @param DeformUniforms deform Its per-pose deform inputs (marshal, do not retain).
* @param FragmentUniforms fragment Its appearance (marshal, do not retain).
* @param DrawTextures textures The textures it samples.
*/
fun drawPuppetMesh(mesh: GpuMesh, deform: DeformUniforms, fragment: FragmentUniforms, textures: DrawTextures)
/**
* Draws one glue art mesh, welding against pass-1's positions.
*
* @param GpuMesh mesh The mesh.
* @param DeformedPositionStore store The shared pass-1 positions.
* @param Int baseVertexOffset This mesh's first vertex index in the store.
* @param FloatArray glueIntensities Per-glue weld intensity, by glue index.
* @param FragmentUniforms fragment Its appearance (marshal, do not retain).
* @param DrawTextures textures The textures it samples.
*/
fun drawGlueMesh(
mesh: GpuMesh,
store: DeformedPositionStore,
baseVertexOffset: Int,
glueIntensities: FloatArray,
fragment: FragmentUniforms,
textures: DrawTextures,
)
/**
* Draws the atlas-page underlay quad.
*
* @param GpuTexture atlas The page.
* @param Float pageWidth The page width in texels.
* @param Float pageHeight The page height in texels.
* @param FragmentUniforms fragment Its appearance.
*/
fun drawAtlasPage(atlas: GpuTexture, pageWidth: Float, pageHeight: Float, fragment: FragmentUniforms)
/**
* Fills the target with the grid backdrop.
*
* @param GridUniforms uniforms The grid's inputs.
*/
fun drawGrid(uniforms: GridUniforms)
/**
* Composites a rendered layer over the destination, blending in-shader (full-screen triangle;
* the pipeline must be [PipelinePurpose.Composite], whose blending is disabled - the shader
* computes the whole blend from the layer and the destination snapshot).
*
* @param CompositeUniforms composite The blend modes, channels, and mask flags (marshal, do not retain).
* @param DrawTextures textures [DrawTextures.compositeLayer] + [DrawTextures.destinationSnapshot],
* plus [DrawTextures.maskCoverage] when the composite is clipped.
*/
fun drawComposite(composite: CompositeUniforms, textures: DrawTextures)
/**
* Draws one world-origin axis line.
*
* @param AxisLineUniforms uniforms The line's inputs.
*/
fun drawAxisLine(uniforms: AxisLineUniforms)
/** Ends the pass. */
fun end()
}
/** Records the pass-1 deform capture. */
public interface DeformCapturePassEncoder {
/**
* Evaluates the deform for every vertex of [mesh] and writes each result into the store at
* [destinationVertexOffset] plus the vertex's own index. Draws nothing.
*
* The name describes the EFFECT, not the mechanism, which is what lets the mechanism change without
* touching the renderer: the GL family runs it as transform feedback today and may become a
* point-scatter render once the store is a 2D texture (a texture cannot be a feedback target); Metal
* has no transform feedback at all and would use a compute kernel. None of that reaches here.
*
* @param GpuMesh mesh The mesh to deform.
* @param DeformUniforms deform Its per-pose deform inputs (marshal, do not retain).
* @param DrawTextures textures Its delta and warp control-point textures.
* @param Int destinationVertexOffset This mesh's base index in the store.
* @param Int vertexCount How many vertices to capture.
*/
fun captureDeformedPositions(
mesh: GpuMesh,
deform: DeformUniforms,
textures: DrawTextures,
destinationVertexOffset: Int,
vertexCount: Int,
)
/** Ends the pass. */
fun end()
}
@@ -0,0 +1,416 @@
package org.umamo.render.eval
import org.umamo.runtime.eval.colorAt
import org.umamo.runtime.eval.meshGridDefaultDeltas
import org.umamo.runtime.eval.rotationFormAt
import org.umamo.runtime.eval.scalarAt
import org.umamo.runtime.eval.warpControlPointsAt
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.BlendWeightLimit
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.RotationPivotForm
/*
* Blend-shape ("MorphTarget") evaluation: the additive pass applied on top of the multilinear
* keyform-grid blend.
*
* - A binding's weight is a LINEAR interpolation between the two keys bracketing the driving
* parameter's value; the neutral key (at the parameter default) contributes zero.
* - Out-of-range driving values SATURATE - the end key's full delta is held (Umamo C++ Runtime
* verdict, Model A's ParamEyeSize matrix; a competing hide-on-out-of-range hypothesis was
* overruled).
* - The bracket has NO epsilon, unlike the grid path's EPS_KEY snapping - mirrored from the
* reference runtime for ULP parity.
* - The weight is multiplied by the MINIMUM over the binding's limit curves (end-clamped
* piecewise-linear over OTHER parameters); Model B-measured: a half-ramp scales deltas by
* exactly 0.5000.
* - Deltas are relative to the object's grid form INTERPOLATED AT THE DEFAULT POSE, not the rest
* shape (refuted 16/16 on Model A). Forms with a null entry (an inserted neutral) never reach
* the contribution list.
*/
/** One active key of a binding at the current pose: the key's form index and its net weight. */
internal class ActiveBlendKey(val keyIndex: Int, val weight: Float)
/**
* Resolves which of [binding]'s keys contribute at [value], with the net weight of each
* (bracket interpolation x [limitMultiplier]). At most two entries; EMPTY at the neutral value,
* so the default pose stays arithmetic-free. Out-of-range values saturate to the end key.
*
* @param BlendShapeBinding binding The binding to resolve.
* @param Float value The driving parameter's current value.
* @param Float limitMultiplier The binding's min-combined limit multiplier (0..1).
* @return List<ActiveBlendKey> The active keys with nonzero weight.
*/
internal fun activeBlendKeys(
binding: BlendShapeBinding<*>,
value: Float,
limitMultiplier: Float,
): List<ActiveBlendKey> {
if (limitMultiplier <= 0f) {
return emptyList()
}
val keys = binding.keys
if (keys.size < 2) {
// A lone key is necessarily the neutral (ingest always inserts it): nothing to add.
return emptyList()
}
// Saturating bracket, no epsilon: grid = last key <= value, clamped to the ends.
var lowerKeyIndex = 0
while (lowerKeyIndex + 1 < keys.size && keys[lowerKeyIndex + 1] <= value) {
lowerKeyIndex++
}
val span = if (lowerKeyIndex + 1 < keys.size) keys[lowerKeyIndex + 1] - keys[lowerKeyIndex] else 0f
val fraction =
when {
value <= keys[0] -> 0f
lowerKeyIndex + 1 >= keys.size -> 0f
span > 0f -> (value - keys[lowerKeyIndex]) / span
else -> 0f
}
val active = ArrayList<ActiveBlendKey>(2)
val lowerWeight = (1f - fraction) * limitMultiplier
if (lowerKeyIndex != binding.neutralIndex && lowerWeight > 0f) {
active.add(ActiveBlendKey(lowerKeyIndex, lowerWeight))
}
val upperWeight = fraction * limitMultiplier
if (fraction > 0f && lowerKeyIndex + 1 != binding.neutralIndex && upperWeight > 0f) {
active.add(ActiveBlendKey(lowerKeyIndex + 1, upperWeight))
}
return active
}
/**
* The binding's blend-weight limit multiplier at the current pose: the MINIMUM over its limit
* curves, each an end-clamped piecewise-linear (value, weight) map over another parameter.
* 1 when the binding has no limits.
*
* @param List limits The binding's limit curves.
* @param Function paramValue Current value per parameter id.
* @return Float The multiplier in [0..1] (whatever the curves yield).
*/
internal fun limitMultiplier(limits: List<BlendWeightLimit>, paramValue: (ParameterId) -> Float): Float {
var multiplier = 1f
for (limit in limits) {
val points = limit.points
if (points.isEmpty()) {
continue
}
val value = paramValue(limit.parameterId)
val capped =
when {
value <= points.first().value -> points.first().weight
value >= points.last().value -> points.last().weight
else -> {
var lowerPointIndex = 0
while (lowerPointIndex + 1 < points.size && points[lowerPointIndex + 1].value <= value) {
lowerPointIndex++
}
val lower = points[lowerPointIndex]
val upper = points[lowerPointIndex + 1]
val span = upper.value - lower.value
if (span > 0f) {
val fraction = (value - lower.value) / span
lower.weight + fraction * (upper.weight - lower.weight)
} else {
lower.weight
}
}
}
if (capped < multiplier) {
multiplier = capped
}
}
return multiplier
}
/** One active mesh blend contribution: the form, its net weight, and its (binding, key) identity. */
internal class MeshBlendContribution(
val bindingIndex: Int,
val keyIndex: Int,
val form: MeshForm,
val weight: Float,
)
/**
* A mesh drawable's resolved blend state at one pose: the active contributions plus the shared
* delta reference (the grid form at the DEFAULT pose, as deltas vs the rest mesh - static per
* drawable, null when the drawable is ungridded so the reference is zero).
*/
internal class MeshBlendState(
val contributions: List<MeshBlendContribution>,
val referenceDeltas: FloatArray?,
val referenceDrawOrder: Float,
val referenceOpacity: Float,
// Default to the channel identities: a drawable with no color tables has no reference to subtract,
// and the identities make the subtraction a no-op rather than a shift.
val referenceMultiplyColor: ColorRgb = ColorRgb.MultiplyIdentity,
val referenceScreenColor: ColorRgb = ColorRgb.ScreenIdentity,
)
/**
* Resolves [drawable]'s blend-shape state at the current pose, or null when it has no bindings
* (the caller then takes the exact pre-blend-shape code path).
*
* @param Drawable drawable The drawable.
* @param Function paramValue Current value per parameter id.
* @param Function defaultValue Default value per parameter id (the neutral pose).
* @return MeshBlendState? The resolved state, or null when binding-free.
*/
internal fun meshBlendState(
drawable: Drawable,
paramValue: (ParameterId) -> Float,
defaultValue: (ParameterId) -> Float,
): MeshBlendState? {
if (drawable.blendShapes.isEmpty()) {
return null
}
val contributions = ArrayList<MeshBlendContribution>()
for (bindingIndex in drawable.blendShapes.indices) {
val binding = drawable.blendShapes[bindingIndex]
val active =
activeBlendKeys(binding, paramValue(binding.parameterId), limitMultiplier(binding.limits, paramValue))
for (key in active) {
val form = binding.forms[key.keyIndex] ?: continue
contributions.add(MeshBlendContribution(bindingIndex, key.keyIndex, form, key.weight))
}
}
// The reference is the entity's state at the DEFAULT pose (E5): geometry deltas vs the rest mesh,
// plus each scalar channel's own value there. An untracked or out-of-range channel resolves to the
// drawable's static, which for an imported drawable is Cubism's 500 / full opacity - the same
// statics scalarAt falls back to everywhere else, so the evaluator's subtraction still cancels exactly.
return MeshBlendState(
contributions = contributions,
referenceDeltas = meshGridDefaultDeltas(drawable, defaultValue),
referenceDrawOrder = drawable.channelGrids.scalarAt(FormChannel.DRAW_ORDER, drawable.drawOrder, defaultValue),
referenceOpacity = drawable.channelGrids.scalarAt(FormChannel.OPACITY, drawable.opacity, defaultValue),
referenceMultiplyColor =
drawable.channelGrids.colorAt(FormChannel.MULTIPLY_COLOR, drawable.multiplyColor, defaultValue),
referenceScreenColor =
drawable.channelGrids.colorAt(FormChannel.SCREEN_COLOR, drawable.screenColor, defaultValue),
)
}
/**
* The summed weighted control-point delta of [warp]'s blend bindings at the current pose, or null
* when nothing contributes. Deltas are relative to the lattice's grid form at the DEFAULT pose
* (E5); WarpForm control points are absolute, so the reference is subtracted here.
*
* @param Deformer.Warp warp The warp deformer.
* @param Function paramValue Current value per parameter id.
* @param Function defaultValue Default value per parameter id.
* @return FloatArray? Interleaved control-point deltas to ADD to the grid-blended lattice, or null.
*/
internal fun warpBlendDeltas(
warp: Deformer.Warp,
paramValue: (ParameterId) -> Float,
defaultValue: (ParameterId) -> Float,
): FloatArray? {
if (warp.blendShapes.isEmpty()) {
return null
}
var deltas: FloatArray? = null
var reference: FloatArray? = null
for (binding in warp.blendShapes) {
val active =
activeBlendKeys(binding, paramValue(binding.parameterId), limitMultiplier(binding.limits, paramValue))
for (key in active) {
val form = binding.forms[key.keyIndex] ?: continue
if (reference == null) {
reference = warpControlPointsAt(warp.geometryGrid, defaultValue) ?: FloatArray(form.controlPoints.size)
}
val target = deltas ?: FloatArray(form.controlPoints.size).also { deltas = it }
for (componentIndex in target.indices) {
target[componentIndex] += key.weight * (form.controlPoints[componentIndex] - reference[componentIndex])
}
}
}
return deltas
}
/** A rotation deformer's summed weighted blend deltas (the reflect flags are not blendable). */
internal class RotationBlendDeltas(
val originX: Float,
val originY: Float,
val angle: Float,
val scale: Float,
)
/**
* The summed weighted affine deltas of [rotation]'s blend bindings at the current pose, or null
* when nothing contributes. Deltas are relative to the rotation's grid form at the DEFAULT pose
* (E5); RotationForm fields are absolute, so the reference is subtracted here.
*
* @param Deformer.Rotation rotation The rotation deformer.
* @param Function paramValue Current value per parameter id.
* @param Function defaultValue Default value per parameter id.
* @return RotationBlendDeltas? The deltas to ADD to the grid-blended transform, or null.
*/
internal fun rotationBlendDeltas(
rotation: Deformer.Rotation,
paramValue: (ParameterId) -> Float,
defaultValue: (ParameterId) -> Float,
): RotationBlendDeltas? {
if (rotation.blendShapes.isEmpty()) {
return null
}
var originX = 0f
var originY = 0f
var angle = 0f
var scale = 0f
var contributed = false
var reference: RotationPivotForm? = null
for (binding in rotation.blendShapes) {
val active =
activeBlendKeys(binding, paramValue(binding.parameterId), limitMultiplier(binding.limits, paramValue))
for (key in active) {
val form = binding.forms[key.keyIndex] ?: continue
if (reference == null) {
// The identity fallback mirrors the importer's, so the subtraction cancels exactly even for
// an unkeyed rotation. Flips are FLAG channels and never take part in a blend-shape delta.
reference = rotationFormAt(rotation.geometryGrid, defaultValue)
?: RotationPivotForm(0f, 0f, 0f, 1f)
}
originX += key.weight * (form.originX - reference.originX)
originY += key.weight * (form.originY - reference.originY)
angle += key.weight * (form.angle - reference.angle)
scale += key.weight * (form.scale - reference.scale)
contributed = true
}
}
return if (contributed) RotationBlendDeltas(originX, originY, angle, scale) else null
}
/**
* A deformer's summed weighted blend-shape CHANNEL deltas - the render channels that cascade onto
* every drawable underneath, as additive offsets to be applied on top of the grid blend.
*/
internal class DeformerBlendChannelDeltas(
val opacity: Float,
val multiplyColor: ColorRgb,
val screenColor: ColorRgb,
)
/**
* Sums [bindings]' weighted channel deltas at the current pose, or null when nothing contributes.
*
* The forms carry each channel's value as (stored delta + the grid-at-default reference), the same
* convention the geometry uses, so the reference is subtracted back out here. Sampling the reference
* from [channelGrids] rather than from the form list is what makes an UNKEYED channel cancel exactly:
* both sides then resolve to the deformer's static.
*
* Warp and rotation share this because their channel triple is identical - only the geometry payload
* differs - and two copies would drift the moment one gained a clamp the other lacked.
*
* @param List bindings The deformer's blend bindings.
* @param ChannelGrids channelGrids The deformer's own keyform tracks (the reference source).
* @param Float staticOpacity The deformer's static opacity.
* @param ColorRgb staticMultiply The deformer's static multiply color.
* @param ColorRgb staticScreen The deformer's static screen color.
* @param Function paramValue Current value per parameter id.
* @param Function defaultValue Default value per parameter id (the neutral pose).
* @return DeformerBlendChannelDeltas? The summed offsets, or null when nothing contributes.
*/
internal fun <F : Any> deformerBlendChannelDeltas(
bindings: List<BlendShapeBinding<F>>,
channelGrids: ChannelGrids,
staticOpacity: Float,
staticMultiply: ColorRgb,
staticScreen: ColorRgb,
paramValue: (ParameterId) -> Float,
defaultValue: (ParameterId) -> Float,
channelsOf: (F) -> DeformerBlendChannelDeltas,
): DeformerBlendChannelDeltas? {
if (bindings.isEmpty()) {
return null
}
var opacity = 0f
var multiplyRed = 0f
var multiplyGreen = 0f
var multiplyBlue = 0f
var screenRed = 0f
var screenGreen = 0f
var screenBlue = 0f
var contributed = false
var reference: DeformerBlendChannelDeltas? = null
for (binding in bindings) {
val active =
activeBlendKeys(binding, paramValue(binding.parameterId), limitMultiplier(binding.limits, paramValue))
for (key in active) {
val form = binding.forms[key.keyIndex] ?: continue
if (reference == null) {
reference =
DeformerBlendChannelDeltas(
channelGrids.scalarAt(FormChannel.OPACITY, staticOpacity, defaultValue),
channelGrids.colorAt(FormChannel.MULTIPLY_COLOR, staticMultiply, defaultValue),
channelGrids.colorAt(FormChannel.SCREEN_COLOR, staticScreen, defaultValue),
)
}
val channels = channelsOf(form)
contributed = true
opacity += key.weight * (channels.opacity - reference.opacity)
multiplyRed += key.weight * (channels.multiplyColor.red - reference.multiplyColor.red)
multiplyGreen += key.weight * (channels.multiplyColor.green - reference.multiplyColor.green)
multiplyBlue += key.weight * (channels.multiplyColor.blue - reference.multiplyColor.blue)
screenRed += key.weight * (channels.screenColor.red - reference.screenColor.red)
screenGreen += key.weight * (channels.screenColor.green - reference.screenColor.green)
screenBlue += key.weight * (channels.screenColor.blue - reference.screenColor.blue)
}
}
if (!contributed) {
return null
}
return DeformerBlendChannelDeltas(
opacity,
ColorRgb(multiplyRed, multiplyGreen, multiplyBlue),
ColorRgb(screenRed, screenGreen, screenBlue),
)
}
/**
* A part's summed weighted blend-shape draw-order delta at the current pose, or null when nothing
* contributes.
*
* Draw order is a part's only blendable channel, so unlike the drawable and deformer paths there is
* one scalar to sum. The reference is the channel's value at the DEFAULT pose - sampled from the
* part's own track, falling back to its static - which is exactly what the import added, so the two
* cancel.
*
* @param Part part The part.
* @param Function paramValue Current value per parameter id.
* @param Function defaultValue Default value per parameter id (the neutral pose).
* @return Float? The summed delta, or null when the part has no active contribution.
*/
internal fun partBlendDrawOrderDelta(
part: Part,
paramValue: (ParameterId) -> Float,
defaultValue: (ParameterId) -> Float,
): Float? {
if (part.blendShapes.isEmpty()) {
return null
}
var delta = 0f
var contributed = false
var reference: Float? = null
for (binding in part.blendShapes) {
val active =
activeBlendKeys(binding, paramValue(binding.parameterId), limitMultiplier(binding.limits, paramValue))
for (key in active) {
val form = binding.forms[key.keyIndex] ?: continue
if (reference == null) {
reference =
part.channelGrids.scalarAt(FormChannel.DRAW_ORDER, part.drawOrder.toFloat(), defaultValue)
}
contributed = true
delta += key.weight * (form.drawOrder - reference)
}
}
return if (contributed) delta else null
}
@@ -0,0 +1,21 @@
package org.umamo.render.eval
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PuppetModel
/**
* CPU implementation of [DeformationEvaluator]. Deformation is split into a cheap, backend-neutral
* [preparePose] (keyform weights + baked deformer transforms) and the per-vertex [applyCpuDeform] that
* finishes it (blend → cascade → Y-flip → glue). The GPU path reuses the same [preparePose] and
* uploads its inputs to a vertex shader instead of finishing on the CPU.
*/
class CpuDeformationEvaluator : DeformationEvaluator {
/**
* Evaluates [model] at [parameters], falling back to each parameter's default when unspecified.
*
* @param PuppetModel model The rig.
* @param Map parameters Parameter id → value (partial; the rest default).
* @return DeformedGeometry World positions per visible drawable.
*/
override fun evaluate(model: PuppetModel, parameters: Map<ParameterId, Float>): DeformedGeometry = applyCpuDeform(model, preparePose(model, parameters))
}
@@ -0,0 +1,356 @@
package org.umamo.render.eval
import org.umamo.runtime.eval.WeightedCell
import org.umamo.runtime.eval.colorAt
import org.umamo.runtime.eval.gridCorners
import org.umamo.runtime.eval.scalarAt
import org.umamo.runtime.eval.scalarOrNull
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.DEFAULT_DRAW_ORDER
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.GluePair
import org.umamo.runtime.model.KeyableTarget
import org.umamo.runtime.model.KeyformOwner
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RenderGroup
/**
* Backend-neutral per-pose deform inputs for one drawable - the cheap output of [preparePose]: which
* keyform cells are active and their weights ([corners]), the mesh's baked parent-deformer transform
* ([parentWorld]; null for a direct, deformer-less mesh), and the blended scalar attributes. [corners]
* null means the mesh is hidden at this pose; [isParented] with a null [parentWorld] means a hidden
* ancestor deformer (also hidden). Nothing here is per-vertex - the CPU finishes it in [applyCpuDeform],
* and the GPU path uploads the same corners (→ weight uniforms) + baked transform instead.
*/
internal class DrawableDeformInputs(
val drawableId: DrawableId,
val corners: List<WeightedCell>?,
val parentWorld: DeformerWorld?,
val isParented: Boolean,
val drawOrder: Float,
val opacity: Float,
val multiplyColor: ColorRgb = ColorRgb.MultiplyIdentity,
val screenColor: ColorRgb = ColorRgb.ScreenIdentity,
val blend: MeshBlendState? = null,
)
/**
* The corner set of an entity with no keyform grid: one full-weight corner into a cell map that holds
* nothing, so every blend contributes zero and the entity evaluates at its rest state.
*
* Shared rather than rebuilt per drawable per frame, and deliberately NOT an empty list - an empty corner
* set would make the weights sum to zero, which is a different thing entirely.
*/
private val REST_CORNERS: List<WeightedCell> = listOf(WeightedCell(0, 1f))
/** A glue affecter with its pose-blended weld [intensity] already resolved, so the apply pass is param-free. */
internal class GlueInputs(
val meshA: DrawableId,
val meshB: DrawableId,
val pairs: List<GluePair>,
val intensity: Float,
)
/**
* The full per-pose, backend-neutral deform inputs ([preparePose]'s output): per-drawable weights + baked
* transforms and the resolved glues. The CPU finishes it per vertex via [applyCpuDeform]; the GPU path
* uploads the same data as uniforms instead of re-uploading every deformed vertex - that re-use is exactly
* why the deformation is split into a cheap "prepare" and a backend-specific "apply".
*/
internal class PoseDeformInputs(
val drawables: List<DrawableDeformInputs>,
val glues: List<GlueInputs>,
/** Pose-blended draw order per grouped part (animated part order); missing → the static value. */
val partDrawOrders: Map<PartId, Float> = emptyMap(),
/**
* Pose-blended composite channels per ISOLATED part (opacity, multiply/screen colors), present
* for every isolated group - a static or out-of-range part carries its PartComposite fallbacks,
* so the composite pass never has to re-derive them.
*/
val partCompositeStates: Map<PartId, PartRenderState> = emptyMap(),
)
/**
* Computes the cheap, backend-neutral deform inputs for [model] at [parameters]: the multilinear keyform
* weights per mesh and each mesh's baked deformer-cascade transform - never per-vertex geometry. Shared
* verbatim by the CPU ([applyCpuDeform]) and the eventual GPU apply paths.
*
* @param PuppetModel model The rig.
* @param Map parameters Parameter id → value (partial; the rest default).
* @param Map channelOverrides Pending unkeyed channel edits, which win over the stored value - how
* a value the user typed but has not keyed shows in the viewport without entering the document.
* @return PoseDeformInputs The backend-neutral per-pose inputs.
*/
internal fun preparePose(
model: PuppetModel,
parameters: Map<ParameterId, Float>,
channelOverrides: Map<KeyableTarget, ChannelValue> = emptyMap(),
): PoseDeformInputs {
val defaults = model.parameters.associate { it.id to it.default }
val paramValue: (ParameterId) -> Float = { parameters[it] ?: defaults[it] ?: 0f }
val defaultValue: (ParameterId) -> Float = { defaults[it] ?: 0f }
// Null in the steady state (no pending unkeyed edit), so every lookup below short-circuits before
// constructing its KeyableTarget key - the per-frame path otherwise allocated a handful of key
// objects per entity purely to probe an empty map.
val overrides = channelOverrides.takeIf { pending -> pending.isNotEmpty() }
val deformerWorlds = buildDeformerWorlds(model.deformers, paramValue, defaultValue, channelOverrides)
val drawables = ArrayList<DrawableDeformInputs>(model.drawables.size)
for (drawable in model.drawables) {
if (drawable.mesh?.positions == null) {
continue
}
// An UNKEYED drawable renders at its rest mesh rather than vanishing: one full-weight corner into
// an empty cell map contributes no deltas, and every blend site already treats a missing cell as a
// zero contribution. Null corners keep meaning HIDDEN (a pose outside a keyed grid's range), so
// "no grid" and "out of range" stay distinguishable - they are opposite outcomes.
val grid = drawable.geometryGrid
val corners = if (grid != null) gridCorners(grid, paramValue) else REST_CORNERS
val parentDeformerId = drawable.parentDeformerId
val parentWorld = parentDeformerId?.let { deformerWorlds[it] }
val blend = meshBlendState(drawable, paramValue, defaultValue)
// Each channel resolves against its own track and falls back to the drawable's static; a channel
// out of range never hides, which is the geometry grid's decision alone (corners == null above).
val drawableOwner = KeyformOwner.Drawable(drawable.id)
var drawOrder =
drawable.channelGrids.scalarAt(
FormChannel.DRAW_ORDER,
drawable.drawOrder,
paramValue,
overrides?.get(KeyableTarget(drawableOwner, FormChannel.DRAW_ORDER)),
)
var opacity =
drawable.channelGrids.scalarAt(
FormChannel.OPACITY,
drawable.opacity,
paramValue,
overrides?.get(KeyableTarget(drawableOwner, FormChannel.OPACITY)),
)
var multiplyColor =
drawable.channelGrids.colorAt(
FormChannel.MULTIPLY_COLOR,
drawable.multiplyColor,
paramValue,
overrides?.get(KeyableTarget(drawableOwner, FormChannel.MULTIPLY_COLOR)),
)
var screenColor =
drawable.channelGrids.colorAt(
FormChannel.SCREEN_COLOR,
drawable.screenColor,
paramValue,
overrides?.get(KeyableTarget(drawableOwner, FormChannel.SCREEN_COLOR)),
)
// Blend shapes: additive deltas on every channel the record carries, not just the scalars. Each
// contribution's form holds its stored delta plus the grid-at-default reference (added at import),
// so subtracting that reference back out here recovers the delta exactly. Opacity and the colours
// clamp to [0,1] only AFTER summing - clamping per contribution would bias a record whose
// neighbours pull the other way. Draw order is left unrounded (the Umamo C++ Runtime rounds
// (int)(0.001+v) at sort time; Umamo sorts floats - MOC3.md §5.6).
if (blend != null) {
for (contribution in blend.contributions) {
val form = contribution.form
drawOrder += contribution.weight * (form.drawOrder - blend.referenceDrawOrder)
opacity += contribution.weight * (form.opacity - blend.referenceOpacity)
multiplyColor =
ColorRgb(
multiplyColor.red + contribution.weight * (form.multiplyColor.red - blend.referenceMultiplyColor.red),
multiplyColor.green +
contribution.weight * (form.multiplyColor.green - blend.referenceMultiplyColor.green),
multiplyColor.blue +
contribution.weight * (form.multiplyColor.blue - blend.referenceMultiplyColor.blue),
)
screenColor =
ColorRgb(
screenColor.red + contribution.weight * (form.screenColor.red - blend.referenceScreenColor.red),
screenColor.green + contribution.weight * (form.screenColor.green - blend.referenceScreenColor.green),
screenColor.blue + contribution.weight * (form.screenColor.blue - blend.referenceScreenColor.blue),
)
}
opacity = opacity.coerceIn(0f, 1f)
multiplyColor = multiplyColor.coerceToUnit()
screenColor = screenColor.coerceToUnit()
}
// Then the parent deformer chain's accumulated channels. A deformer's opacity multiplies, its
// multiply color multiplies, its screen color screens - each already folded over every ancestor
// deformer by buildDeformerWorlds, so one composition here covers the whole chain. Clamped
// because a blended color can leave [0,1] at the ends of a keyed range.
parentWorld?.let { world ->
opacity *= world.accumulatedOpacity
multiplyColor =
ColorRgb(
(multiplyColor.red * world.accumulatedMultiplyColor.red).coerceIn(0f, 1f),
(multiplyColor.green * world.accumulatedMultiplyColor.green).coerceIn(0f, 1f),
(multiplyColor.blue * world.accumulatedMultiplyColor.blue).coerceIn(0f, 1f),
)
screenColor =
ColorRgb(
screenCompose(screenColor.red, world.accumulatedScreenColor.red).coerceIn(0f, 1f),
screenCompose(screenColor.green, world.accumulatedScreenColor.green).coerceIn(0f, 1f),
screenCompose(screenColor.blue, world.accumulatedScreenColor.blue).coerceIn(0f, 1f),
)
}
drawables.add(
DrawableDeformInputs(
drawableId = drawable.id,
corners = corners,
parentWorld = parentWorld,
isParented = parentDeformerId != null,
drawOrder = drawOrder,
opacity = opacity,
multiplyColor = multiplyColor,
screenColor = screenColor,
blend = blend,
),
)
}
val glues =
model.glues.map { glue ->
GlueInputs(
meshA = glue.meshA,
meshB = glue.meshB,
pairs = glue.pairs,
intensity =
glue.channelGrids.scalarAt(
FormChannel.GLUE_INTENSITY,
glue.intensity,
paramValue,
overrides?.get(KeyableTarget(KeyformOwner.Glue(glue.meshA, glue.meshB), FormChannel.GLUE_INTENSITY)),
),
)
}
// Blend each group's (animated) part draw order, so the renderer can position whole groups per
// pose - part groups with parameter-driven draw order swap front/back as their parameter moves.
// The same walk blends each ISOLATED group's composite channels (opacity, multiply/screen
// colors), falling back to the PartComposite statics when the part has no grid or the axis is
// out of range.
val partDrawOrders = HashMap<PartId, Float>()
val partCompositeStates = HashMap<PartId, PartRenderState>()
// The render tree carries a group's tracks but not its part's blend records, so the blend pass
// needs the part itself. Taken from the model, which memoizes it: this runs once per rendered
// frame, so building the map here would allocate one entry per part per frame for data that is
// immutable across all of them.
val partsById = model.partById
fun blendGroupStates(group: RenderGroup) {
val partId = group.partId
val channels = group.channelGrids
val partOwner = partId?.let { KeyformOwner.Part(it) }
if (partId != null && partOwner != null) {
// Null when the part has no draw-order track or the pose is out of its range; with no blend
// record contributing either, the map entry is then left ABSENT so the renderer keeps the
// part's static slot - the map's sparseness is the signal.
val tracked =
channels.scalarOrNull(
FormChannel.DRAW_ORDER,
paramValue,
overrides?.get(KeyableTarget(partOwner, FormChannel.DRAW_ORDER)),
)
// A part-target blend record moves the slot too, and it can do so on a part with no track at
// all - so an entry appears whenever EITHER contributes, with the static standing in as the
// base when only the record does.
val blendDelta = partsById[partId]?.let { part -> partBlendDrawOrderDelta(part, paramValue, defaultValue) }
if (tracked != null || blendDelta != null) {
val base = tracked ?: partsById[partId]?.drawOrder?.toFloat() ?: DEFAULT_DRAW_ORDER.toFloat()
partDrawOrders[partId] = base + (blendDelta ?: 0f)
}
}
val composite = group.composite
if (partId != null && composite != null) {
// Each composite channel resolves independently against its own static, so an isolated part
// can key opacity alone without dragging its tints onto the same axes.
partCompositeStates[partId] =
PartRenderState(
channels.scalarAt(
FormChannel.OPACITY,
composite.opacity,
paramValue,
partOwner?.let { owner -> overrides?.get(KeyableTarget(owner, FormChannel.OPACITY)) },
),
channels.colorAt(
FormChannel.MULTIPLY_COLOR,
composite.multiplyColor,
paramValue,
partOwner?.let { owner -> overrides?.get(KeyableTarget(owner, FormChannel.MULTIPLY_COLOR)) },
),
channels.colorAt(
FormChannel.SCREEN_COLOR,
composite.screenColor,
paramValue,
partOwner?.let { owner -> overrides?.get(KeyableTarget(owner, FormChannel.SCREEN_COLOR)) },
),
)
}
for (child in group.children) {
if (child is RenderGroup) {
blendGroupStates(child)
}
}
}
blendGroupStates(model.renderRoot)
return PoseDeformInputs(drawables, glues, partDrawOrders, partCompositeStates)
}
/**
* Finishes [inputs] on the CPU: per drawable, blends the active corners into local positions, pushes them
* through the baked parent transform, negates Y, then welds the glue pairs in place. Output is identical
* to evaluating the model in one pass.
*
* @param PuppetModel model The rig (for each drawable's base positions + grid).
* @param PoseDeformInputs inputs The prepared per-pose inputs.
* @return DeformedGeometry World positions + scalars per visible drawable.
*/
internal fun applyCpuDeform(model: PuppetModel, inputs: PoseDeformInputs): DeformedGeometry {
val drawableById = model.drawables.associateBy { it.id }
val worldPositions = HashMap<DrawableId, FloatArray>(inputs.drawables.size)
val drawOrders = HashMap<DrawableId, Float>(inputs.drawables.size)
val opacities = HashMap<DrawableId, Float>(inputs.drawables.size)
for (drawableInputs in inputs.drawables) {
val corners = drawableInputs.corners ?: continue
// A parented mesh whose ancestor deformer is hidden produces no geometry (the cascade omitted it).
if (drawableInputs.isParented && drawableInputs.parentWorld == null) {
continue
}
val drawable = drawableById[drawableInputs.drawableId] ?: continue
val base = drawable.mesh?.positions ?: continue
// A null grid is an unkeyed drawable, which deforms to its rest mesh - see preparePose.
worldPositions[drawableInputs.drawableId] =
deformMeshWorldFromCorners(drawable.geometryGrid, base, corners, drawableInputs.parentWorld, drawableInputs.blend)
drawOrders[drawableInputs.drawableId] = drawableInputs.drawOrder
opacities[drawableInputs.drawableId] = drawableInputs.opacity
}
applyGluesResolved(inputs.glues, worldPositions)
return DeformedGeometry(worldPositions, drawOrders, opacities)
}
/**
* Seam-welds each glue's vertex pairs in place from pre-resolved intensities: `A' = A + (B−A)·wA·i`,
* `B' = B + (A−B)·wB·i` (the Umamo C++ Runtime's `applyGlue`, on the Y-flipped world buffers).
*
* @param List<GlueInputs> glues The resolved glue affecters.
* @param Map<DrawableId,FloatArray> worldPositions Per-drawable deformed positions (mutated).
*/
internal fun applyGluesResolved(glues: List<GlueInputs>, worldPositions: Map<DrawableId, FloatArray>) {
for (glue in glues) {
val vertsA = worldPositions[glue.meshA] ?: continue
val vertsB = worldPositions[glue.meshB] ?: continue
val intensity = glue.intensity
for (pair in glue.pairs) {
val indexA = pair.indexA * 2
val indexB = pair.indexB * 2
if (indexA + 1 >= vertsA.size || indexB + 1 >= vertsB.size) {
continue
}
val ax = vertsA[indexA]
val ay = vertsA[indexA + 1]
val bx = vertsB[indexB]
val by = vertsB[indexB + 1]
vertsA[indexA] = (bx - ax) * pair.weightA * intensity + ax
vertsA[indexA + 1] = (by - ay) * pair.weightA * intensity + ay
vertsB[indexB] = (ax - bx) * pair.weightB * intensity + bx
vertsB[indexB + 1] = (ay - by) * pair.weightB * intensity + by
}
}
}
@@ -0,0 +1,106 @@
package org.umamo.render.eval
import kotlin.math.cos
import kotlin.math.sin
import org.umamo.runtime.eval.warpApply as runtimeWarpApply
import org.umamo.runtime.eval.warpExtrap as runtimeWarpExtrap
import org.umamo.runtime.eval.warpInGrid as runtimeWarpInGrid
// The float pi the Umamo C++ Runtime uses (matches its sincosf bit-for-bit)
internal const val PI_F = 3.1415927f
/**
* In-grid warp transform — delegates to [org.umamo.runtime.eval.warpInGrid].
*
* @return Boolean true when in grid (and written), false when outside.
*/
internal fun warpInGrid(
cp: FloatArray,
cols: Int,
rows: Int,
bilinear: Boolean,
u: Float,
v: Float,
out: FloatArray,
outIndex: Int,
): Boolean = runtimeWarpInGrid(cp, cols, rows, bilinear, u, v, out, outIndex)
/** Out-of-grid warp extrapolation — delegates to [org.umamo.runtime.eval.warpExtrap]. */
internal fun warpExtrap(cp: FloatArray, cols: Int, rows: Int, u: Float, v: Float, out: FloatArray, outIndex: Int) {
runtimeWarpExtrap(cp, cols, rows, u, v, out, outIndex)
}
/** Warp-transforms `(u, v)` through [cp] — delegates to [org.umamo.runtime.eval.warpApply]. */
internal fun warpApply(
cp: FloatArray,
cols: Int,
rows: Int,
bilinear: Boolean,
u: Float,
v: Float,
out: FloatArray,
outIndex: Int,
) {
runtimeWarpApply(cp, cols, rows, bilinear, u, v, out, outIndex)
}
/**
* A rotation deformer's baked world affine - the per-vertex-invariant coefficients (xformSetup's exact
* grouping), applied as `x' = c15·y + c12·x + ox`, `y' = c13·y + c14·x + oy`.
*/
internal class RotationXform(
val c12: Float,
val c13: Float,
val c14: Float,
val c15: Float,
val ox: Float,
val oy: Float,
) {
/**
* Applies the affine to point `(x, y)`, writing the result to `out[outIndex]`,`out[outIndex+1]`.
*
* @param Float x Input x.
* @param Float y Input y.
* @param FloatArray out Destination for the transformed point.
* @param Int outIndex Index of the x slot in [out] (y is `outIndex+1`).
*/
fun apply(x: Float, y: Float, out: FloatArray, outIndex: Int) {
out[outIndex] = c15 * y + c12 * x + ox
out[outIndex + 1] = y * c13 + x * c14 + oy
}
}
/**
* Builds a [RotationXform] from a rotation deformer's world angle (degrees), scale, reflection flags,
* and origin.
*
* @param Float angleDegrees World rotation angle in degrees.
* @param Float scale World scale.
* @param Boolean flipX Reflect across the vertical axis.
* @param Boolean flipY Reflect across the horizontal axis.
* @param Float ox World origin x.
* @param Float oy World origin y.
* @return RotationXform The baked affine.
*/
internal fun rotationXform(
angleDegrees: Float,
scale: Float,
flipX: Boolean,
flipY: Boolean,
ox: Float,
oy: Float,
): RotationXform {
val radians = angleDegrees * PI_F / 180f
val sn = sin(radians.toDouble()).toFloat()
val cs = cos(radians.toDouble()).toFloat()
val fx = if (flipX) -1f else 1f
val fy = if (flipY) -1f else 1f
return RotationXform(
c12 = cs * scale * fx,
c13 = fy * cs * scale,
c14 = fx * scale * sn,
c15 = -sn * scale * fy,
ox = ox,
oy = oy,
)
}
@@ -0,0 +1,39 @@
package org.umamo.render.eval
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PuppetModel
/**
* Computed render state for one parameter pose. [worldPositions] are interleaved (x,y) world vertices
* per drawable (in the CMO3/MOC3 reverse-coordinate / Y-down model space). [drawOrder] and
* [opacity] are the per-drawable scalars blended from the same keyform grid with the same weights -
* [drawOrder] is the primary render-order sort key (the parts-tree order breaks ties), [opacity] is
* multiplied into the drawable's alpha. All three maps share the same visible-drawable keys; hidden
* drawables are absent from every map.
*/
class DeformedGeometry(
val worldPositions: Map<DrawableId, FloatArray>,
val drawOrder: Map<DrawableId, Float>,
val opacity: Map<DrawableId, Float>,
)
/**
* Evaluates a [PuppetModel] at a set of parameter values into drawable geometry.
*
* The core math is parameter-driven morph blending (`p = base + Σ wᵢ·Δᵢ`, multilinear across the
* N-D keyform grid) composed through the deformer hierarchy. The weights are cheap and computed
* CPU-side; the per-vertex delta-sum runs in a vertex shader in `:gpu`.
*
* パラメータ値からドロウアブルのジオメトリを評価する契約。
*/
interface DeformationEvaluator {
/**
* Evaluates [model] at [parameters]; unspecified parameters fall back to their defaults.
*
* @param PuppetModel model The rig.
* @param Map parameters Parameter id → value (partial; the rest default).
* @return DeformedGeometry World positions per visible drawable.
*/
fun evaluate(model: PuppetModel, parameters: Map<ParameterId, Float>): DeformedGeometry
}
@@ -0,0 +1,577 @@
package org.umamo.render.eval
import org.umamo.runtime.eval.WeightedCell
import org.umamo.runtime.eval.cellsByLinearIndex
import org.umamo.runtime.eval.colorAt
import org.umamo.runtime.eval.flagAt
import org.umamo.runtime.eval.gridCorners
import org.umamo.runtime.eval.scalarAt
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.KeyableTarget
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.KeyformOwner
import org.umamo.runtime.model.MeshDeltaForm
import org.umamo.runtime.model.ParameterId
import kotlin.math.atan2
/**
* A deformer's baked world transform - a warp lattice or a rotation affine - through which child
* deformers and bound meshes transform their points. [accY] is the Y-scale accumulator passed to
* child rotation deformers (warps pass the parent's through; rotations contribute their world scale).
*
* The three `accumulated*` channels are the deformer's own render channels composed with every
* ancestor's, and they apply to every DRAWABLE under this deformer (see [DeformerChannels] for the
* composition rules and [preparePose] for where they land). Riggers key a deformer's opacity to
* show and hide a whole subtree, so these are not a decorative extra - ignoring them renders effect
* subtrees permanently visible.
*/
internal sealed interface DeformerWorld {
val accY: Float
/** This deformer's opacity times every ancestor's; multiplies each descendant drawable's own. */
val accumulatedOpacity: Float
/** This deformer's multiply color composed with every ancestor's (componentwise product). */
val accumulatedMultiplyColor: ColorRgb
/** This deformer's screen color composed with every ancestor's (`a + b - a*b` per channel). */
val accumulatedScreenColor: ColorRgb
/**
* Transforms point `(x, y)` through this deformer, writing to `out[outIndex]`,`out[outIndex+1]`.
*
* @param Float x Input x.
* @param Float y Input y.
* @param FloatArray out Destination for the transformed point.
* @param Int outIndex Index of the x slot in [out] (y is `outIndex+1`).
*/
fun apply(x: Float, y: Float, out: FloatArray, outIndex: Int)
}
/**
* A deformer's render channels at one point in the cascade - either its own blended local values or
* those composed with its ancestors'.
*
* @property Float opacity Opacity in [0,1].
* @property ColorRgb multiplyColor Multiply tint (identity = white).
* @property ColorRgb screenColor Screen tint (identity = black).
*/
internal class DeformerChannels(
val opacity: Float,
val multiplyColor: ColorRgb,
val screenColor: ColorRgb,
) {
companion object {
/** The no-op channels a root deformer composes against. */
val Identity: DeformerChannels =
DeformerChannels(1f, ColorRgb.MultiplyIdentity, ColorRgb.ScreenIdentity)
}
}
/**
* Composes a deformer's local channels onto its parent's accumulated ones.
*
* Opacity and multiply color compose by product; screen color composes by the screen operator
* `a + b - a*b`. The identities are chosen so a ROOT deformer needs no special case: multiplying by
* white and screening with black both return the local value unchanged.
*
* @param DeformerChannels local This deformer's own blended channels.
* @param DeformerWorld? parent The parent's world transform, or null at the root.
* @return DeformerChannels The accumulated channels to hand to children and descendant drawables.
*/
internal fun cascadeDeformerChannels(local: DeformerChannels, parent: DeformerWorld?): DeformerChannels {
val parentOpacity = parent?.accumulatedOpacity ?: 1f
val parentMultiply = parent?.accumulatedMultiplyColor ?: ColorRgb.MultiplyIdentity
val parentScreen = parent?.accumulatedScreenColor ?: ColorRgb.ScreenIdentity
return DeformerChannels(
opacity = local.opacity * parentOpacity,
multiplyColor =
ColorRgb(
local.multiplyColor.red * parentMultiply.red,
local.multiplyColor.green * parentMultiply.green,
local.multiplyColor.blue * parentMultiply.blue,
),
screenColor =
ColorRgb(
screenCompose(local.screenColor.red, parentScreen.red),
screenCompose(local.screenColor.green, parentScreen.green),
screenCompose(local.screenColor.blue, parentScreen.blue),
),
)
}
/**
* The screen operator on one channel: `a + b - a*b`.
*
* @param Float a One operand.
* @param Float b The other.
* @return Float The screened channel.
*/
internal fun screenCompose(a: Float, b: Float): Float = a + b - a * b
/**
* A warp deformer's world transform: its baked world control points + lattice mode. The control-point
* fields are `internal` (not `private`) so the GPU renderer in this module can upload them as the
* shader's lattice uniforms - the same baked data the CPU `apply` walks via [warpApply].
*/
internal class WarpWorld(
internal val cp: FloatArray,
internal val cols: Int,
internal val rows: Int,
internal val bilinear: Boolean,
override val accY: Float,
override val accumulatedOpacity: Float = 1f,
override val accumulatedMultiplyColor: ColorRgb = ColorRgb.MultiplyIdentity,
override val accumulatedScreenColor: ColorRgb = ColorRgb.ScreenIdentity,
) : DeformerWorld {
/**
* Warp-transforms `(x, y)` through the baked lattice.
*
* @param Float x Input x.
* @param Float y Input y.
* @param FloatArray out Destination.
* @param Int outIndex Index of the x slot.
*/
override fun apply(x: Float, y: Float, out: FloatArray, outIndex: Int) {
warpApply(cp, cols, rows, bilinear, x, y, out, outIndex)
}
}
/** A rotation deformer's world transform: a baked affine. [xform] is `internal` so the GPU renderer can
* upload its 6 coefficients as shader uniforms (the same affine the CPU `apply` evaluates). */
internal class RotationWorld(
internal val xform: RotationXform,
override val accY: Float,
override val accumulatedOpacity: Float = 1f,
override val accumulatedMultiplyColor: ColorRgb = ColorRgb.MultiplyIdentity,
override val accumulatedScreenColor: ColorRgb = ColorRgb.ScreenIdentity,
) : DeformerWorld {
/**
* Applies the rotation affine to `(x, y)`.
*
* @param Float x Input x.
* @param Float y Input y.
* @param FloatArray out Destination.
* @param Int outIndex Index of the x slot.
*/
override fun apply(x: Float, y: Float, out: FloatArray, outIndex: Int) {
xform.apply(x, y, out, outIndex)
}
}
/**
* Builds every deformer's world transform top-down (parents first), composing each local
* keyform-blended transform with its parent's world transform.
*
* Out-of-range (hidden) deformers, and any whose ancestor is hidden, are omitted from the result. At
* default parameters nothing is hidden, so this only affects out-of-range poses.
*
* @param List deformers All deformers in the model.
* @param Function paramValue Current value for a given parameter id.
* @param Function defaultValue Default value for a given parameter id (the blend-shape delta reference pose).
* @param Map channelOverrides Pending unkeyed channel edits, which win over a deformer's stored channel value.
* @return Map<DeformerId, DeformerWorld> The built world transforms, keyed by deformer id.
*/
internal fun buildDeformerWorlds(
deformers: List<Deformer>,
paramValue: (ParameterId) -> Float,
defaultValue: (ParameterId) -> Float = paramValue,
channelOverrides: Map<KeyableTarget, ChannelValue> = emptyMap(),
): Map<DeformerId, DeformerWorld> {
val worlds = HashMap<DeformerId, DeformerWorld>(deformers.size)
val ids = deformers.mapTo(HashSet()) { it.id }
var pending = deformers
var passes = 0
while (pending.isNotEmpty() && passes <= deformers.size + 2) {
passes++
val deferred = ArrayList<Deformer>()
var built = false
for (deformer in pending) {
val parentId = deformer.parent
val parentKnown = parentId == null || parentId !in ids || parentId in worlds
if (!parentKnown) {
deferred.add(deformer)
continue
}
val parentWorld = parentId?.let { worlds[it] }
val world = buildDeformerWorld(deformer, paramValue, defaultValue, parentWorld, channelOverrides)
if (world != null) {
worlds[deformer.id] = world
built = true
}
}
if (!built) {
break // no progress: the rest are hidden or orphaned
}
pending = deferred
}
return worlds
}
/**
* Builds one deformer's world transform given its parent's (or null at the root).
*
* @param Deformer deformer The deformer.
* @param Function paramValue Current value for a given parameter id.
* @param Function defaultValue Default value for a given parameter id (the blend-shape delta reference pose).
* @param DeformerWorld? parentWorld The parent's world transform, or null.
* @param Map channelOverrides Pending unkeyed channel edits, which win over a deformer's stored channel value.
* @return DeformerWorld? The world transform, or null when hidden.
*/
private fun buildDeformerWorld(
deformer: Deformer,
paramValue: (ParameterId) -> Float,
defaultValue: (ParameterId) -> Float,
parentWorld: DeformerWorld?,
channelOverrides: Map<KeyableTarget, ChannelValue>,
): DeformerWorld? =
when (deformer) {
is Deformer.Warp -> buildWarpWorld(deformer, paramValue, defaultValue, parentWorld, channelOverrides)
is Deformer.Rotation -> buildRotationWorld(deformer, paramValue, defaultValue, parentWorld, channelOverrides)
}
/**
* Builds a warp's world transform: blend its keyform control points, then push each through the parent
* (warps inherit the parent's accY; they add no scale of their own).
*
* @param Deformer.Warp warp The warp deformer.
* @param Function paramValue Current value for a given parameter id.
* @param Function defaultValue Default value for a given parameter id (the blend-shape delta reference pose).
* @param DeformerWorld? parentWorld The parent's world transform, or null.
* @param Map channelOverrides Pending unkeyed channel edits, which win over the warp's stored channel value.
* @return DeformerWorld? The world transform, or null when hidden.
*/
private fun buildWarpWorld(
warp: Deformer.Warp,
paramValue: (ParameterId) -> Float,
defaultValue: (ParameterId) -> Float,
parentWorld: DeformerWorld?,
channelOverrides: Map<KeyableTarget, ChannelValue>,
): DeformerWorld? {
val grid = warp.geometryGrid ?: return null
val corners = gridCorners(grid, paramValue) ?: return null
val cells = cellsByLinearIndex(grid)
val pointCount = (warp.rows + 1) * (warp.columns + 1)
val cp = FloatArray(pointCount * 2)
for (corner in corners) {
val controlPoints = cells[corner.linearIndex]?.form?.controlPoints ?: continue
val count = minOf(cp.size, controlPoints.size)
for (coordIndex in 0 until count) {
cp[coordIndex] += corner.weight * controlPoints[coordIndex]
}
}
// Blend shapes: additive control-point deltas on top of the grid blend, before parent transforms.
warpBlendDeltas(warp, paramValue, defaultValue)?.let { deltas ->
val count = minOf(cp.size, deltas.size)
for (coordIndex in 0 until count) {
cp[coordIndex] += deltas[coordIndex]
}
}
// The render channels are blended, never snapped to the nearest key, or they step instead of fading
// at mid-parameter values. Each track resolves its own corners; pre-compaction those are the same
// corners in the same order as the control points', so the sums are unchanged.
// A constant null in the steady state (no pending edit), so the per-channel lookups below allocate
// no KeyableTarget keys on the per-frame path.
val warpOverride: (FormChannel) -> ChannelValue? =
if (channelOverrides.isEmpty()) {
{ null }
} else {
{ channel -> channelOverrides[KeyableTarget(KeyformOwner.Deformer(warp.id), channel)] }
}
val channels =
cascadeDeformerChannels(
withBlendChannelDeltas(
DeformerChannels(
warp.channelGrids.scalarAt(FormChannel.OPACITY, warp.opacity, paramValue, warpOverride(FormChannel.OPACITY)),
warp.channelGrids.colorAt(
FormChannel.MULTIPLY_COLOR,
warp.multiplyColor,
paramValue,
warpOverride(FormChannel.MULTIPLY_COLOR),
),
warp.channelGrids.colorAt(
FormChannel.SCREEN_COLOR,
warp.screenColor,
paramValue,
warpOverride(FormChannel.SCREEN_COLOR),
),
),
deformerBlendChannelDeltas(
warp.blendShapes,
warp.channelGrids,
warp.opacity,
warp.multiplyColor,
warp.screenColor,
paramValue,
defaultValue,
) { form -> DeformerBlendChannelDeltas(form.opacity, form.multiplyColor, form.screenColor) },
),
parentWorld,
)
val parentAccY = parentWorld?.accY ?: 1f
if (parentWorld != null) {
for (pointIndex in 0 until pointCount) {
parentWorld.apply(cp[pointIndex * 2], cp[pointIndex * 2 + 1], cp, pointIndex * 2)
}
}
return WarpWorld(
cp,
warp.columns,
warp.rows,
warp.isQuadTransform,
parentAccY,
channels.opacity,
channels.multiplyColor,
channels.screenColor,
)
}
/**
* Builds a rotation's world transform: blend its keyform origin/angle/scale (flip snaps to the first
* corner), compose scale with the parent's accY, and - for a non-root - derive the inherited angle by
* numerically probing the parent transform.
*
* @param Deformer.Rotation rotation The rotation deformer.
* @param Function paramValue Current value for a given parameter id.
* @param Function defaultValue Default value for a given parameter id (the blend-shape delta reference pose).
* @param DeformerWorld? parentWorld The parent's world transform, or null.
* @param Map channelOverrides Pending unkeyed channel edits, which win over the rotation's stored channel value.
* @return DeformerWorld? The world transform, or null when hidden.
*/
private fun buildRotationWorld(
rotation: Deformer.Rotation,
paramValue: (ParameterId) -> Float,
defaultValue: (ParameterId) -> Float,
parentWorld: DeformerWorld?,
channelOverrides: Map<KeyableTarget, ChannelValue>,
): DeformerWorld? {
val grid = rotation.geometryGrid ?: return null
val corners = gridCorners(grid, paramValue) ?: return null
val cells = cellsByLinearIndex(grid)
var originX = 0f
var originY = 0f
var scaleAccum = 0f
var angleAccum = 0f
for (corner in corners) {
val form = cells[corner.linearIndex]?.form ?: continue
originX += corner.weight * form.originX
originY += corner.weight * form.originY
scaleAccum += corner.weight * form.scale
angleAccum += corner.weight * form.angle
}
// The render channels blend, never snap to the nearest key (unlike the flip flags below, which are
// not interpolable and take the floor cell).
// A constant null in the steady state, so the lookups allocate nothing (see buildWarpWorld's note).
val rotationOverride: (FormChannel) -> ChannelValue? =
if (channelOverrides.isEmpty()) {
{ null }
} else {
{ channel -> channelOverrides[KeyableTarget(KeyformOwner.Deformer(rotation.id), channel)] }
}
val channels =
cascadeDeformerChannels(
withBlendChannelDeltas(
DeformerChannels(
rotation.channelGrids.scalarAt(
FormChannel.OPACITY,
rotation.opacity,
paramValue,
rotationOverride(FormChannel.OPACITY),
),
rotation.channelGrids.colorAt(
FormChannel.MULTIPLY_COLOR,
rotation.multiplyColor,
paramValue,
rotationOverride(FormChannel.MULTIPLY_COLOR),
),
rotation.channelGrids.colorAt(
FormChannel.SCREEN_COLOR,
rotation.screenColor,
paramValue,
rotationOverride(FormChannel.SCREEN_COLOR),
),
),
deformerBlendChannelDeltas(
rotation.blendShapes,
rotation.channelGrids,
rotation.opacity,
rotation.multiplyColor,
rotation.screenColor,
paramValue,
defaultValue,
) { form -> DeformerBlendChannelDeltas(form.opacity, form.multiplyColor, form.screenColor) },
),
parentWorld,
)
// Blend shapes: additive origin/scale/angle deltas on top of the grid blend (flip stays grid-only).
rotationBlendDeltas(rotation, paramValue, defaultValue)?.let { deltas ->
originX += deltas.originX
originY += deltas.originY
scaleAccum += deltas.scale
angleAccum += deltas.angle
}
// Reflections snap to the floor cell (corner 0 is the all-lower-key corner), which is what flagAt does.
val flipX = rotation.channelGrids.flagAt(FormChannel.FLIP_X, rotation.flipX, paramValue, rotationOverride(FormChannel.FLIP_X))
val flipY = rotation.channelGrids.flagAt(FormChannel.FLIP_Y, rotation.flipY, paramValue, rotationOverride(FormChannel.FLIP_Y))
val angleDegrees = rotation.baseAngle + angleAccum
val parentAccY = parentWorld?.accY ?: 1f
val scale = parentAccY * scaleAccum
val worldPivotX: Float
val worldPivotY: Float
val worldAngle: Float
if (parentWorld == null) {
worldPivotX = originX
worldPivotY = originY
worldAngle = angleDegrees
} else {
// Probe the parent's local rotation at the origin: displace along -Y and read the resulting
// direction. -10 step for a rotation parent, -0.1 for a warp (degenerate steps shrink ×0.1).
val disp = if (parentWorld is RotationWorld) -10f else -0.1f
val scratch = FloatArray(2)
parentWorld.apply(originX, originY, scratch, 0)
val worldPosX = scratch[0]
val worldPosY = scratch[1]
var dx = 0f
var dy = 0f
var probeScale = 1f
var iteration = 0
while (iteration < 10) {
parentWorld.apply(originX, originY + disp * probeScale, scratch, 0)
dx = scratch[0] - worldPosX
dy = scratch[1] - worldPosY
if (dx != 0f || dy != 0f) {
break
}
parentWorld.apply(originX, originY - disp * probeScale, scratch, 0)
dx = worldPosX - scratch[0]
dy = worldPosY - scratch[1]
if (dx != 0f || dy != 0f) {
break
}
probeScale *= 0.1f
iteration++
}
var inherited = atan2(disp.toDouble(), 0.0).toFloat() - atan2(dy.toDouble(), dx.toDouble()).toFloat()
while (inherited > PI_F) {
inherited -= 2f * PI_F
}
while (inherited < -PI_F) {
inherited += 2f * PI_F
}
worldPivotX = worldPosX
worldPivotY = worldPosY
worldAngle = angleDegrees - inherited * 180f / PI_F
}
return RotationWorld(
rotationXform(worldAngle, scale, flipX, flipY, worldPivotX, worldPivotY),
scale,
channels.opacity,
channels.multiplyColor,
channels.screenColor,
)
}
/**
* Deforms a deformer-parented mesh: blend its local vertices, push each through the parent deformer's
* world transform, then negate Y (reverse-coordinate). Returns null when the mesh is hidden.
*
* @param KeyformGrid grid The mesh's keyform grid.
* @param FloatArray base The mesh's rest-pose positions (interleaved x,y).
* @param DeformerWorld parent The mesh's parent deformer's world transform.
* @param Function paramValue Current value for a given parameter id.
* @return FloatArray? World positions (interleaved x,y), or null when hidden.
*/
internal fun deformMeshThroughParent(grid: KeyformGrid<MeshDeltaForm>, base: FloatArray, parent: DeformerWorld, paramValue: (ParameterId) -> Float): FloatArray? {
val local = sampleMeshLocal(grid, base, paramValue) ?: return null
val world = FloatArray(local.size)
val vertexCount = local.size / 2
for (vertexIndex in 0 until vertexCount) {
parent.apply(local[vertexIndex * 2], local[vertexIndex * 2 + 1], world, vertexIndex * 2)
world[vertexIndex * 2 + 1] = -world[vertexIndex * 2 + 1]
}
return world
}
/**
* Deforms a mesh to world positions from precomputed corners: blend `base + Σ wᵢ·Δᵢ`, push each vertex
* through [parent] (or pass through when null - a direct, deformer-less mesh), then negate Y. This is the
* corners-first union of [deformMeshThroughParent] and `evalDirectMeshWorld`, fed by `preparePose`'s
* backend-neutral corner set; output is identical to the parameter-driven path.
*
* @param KeyformGrid grid The mesh's keyform grid.
* @param FloatArray base The mesh's rest-pose positions (interleaved x,y).
* @param List<WeightedCell> corners The active keyform corners + weights.
* @param DeformerWorld? parent The mesh's parent deformer world transform, or null when direct.
* @param MeshBlendState? blend The drawable's resolved blend-shape state, or null when binding-free.
* @return FloatArray World positions (interleaved x,y).
*/
internal fun deformMeshWorldFromCorners(
grid: KeyformGrid<MeshDeltaForm>?,
base: FloatArray,
corners: List<WeightedCell>,
parent: DeformerWorld?,
blend: MeshBlendState? = null,
): FloatArray {
val local = blendLocalFromCorners(grid, base, corners)
// Blend shapes: additive per-vertex deltas (form minus the grid-at-default reference) on top of
// the grid blend, before the parent transform. Binding-free drawables never reach this loop.
if (blend != null) {
for (contribution in blend.contributions) {
val deltas = contribution.form.positionDeltas
val count = minOf(local.size, deltas.size)
for (componentIndex in 0 until count) {
val reference = blend.referenceDeltas?.get(componentIndex) ?: 0f
local[componentIndex] += contribution.weight * (deltas[componentIndex] - reference)
}
}
}
val world = FloatArray(local.size)
val vertexCount = local.size / 2
for (vertexIndex in 0 until vertexCount) {
if (parent != null) {
parent.apply(local[vertexIndex * 2], local[vertexIndex * 2 + 1], world, vertexIndex * 2)
} else {
world[vertexIndex * 2] = local[vertexIndex * 2]
world[vertexIndex * 2 + 1] = local[vertexIndex * 2 + 1]
}
world[vertexIndex * 2 + 1] = -world[vertexIndex * 2 + 1]
}
return world
}
/**
* Applies a deformer's blend-shape channel offsets onto its grid-blended channels.
*
* Additive like every other blend contribution, clamped to 0..1 only AFTER the sum so a record whose
* neighbours pull the other way is not biased. Returns [local] untouched when nothing contributes,
* which keeps the blend-free path allocation-identical to before.
*
* @param DeformerChannels local The deformer's own grid-blended channels.
* @param DeformerBlendChannelDeltas? deltas The summed blend offsets, or null when none apply.
* @return DeformerChannels The channels to cascade.
*/
internal fun withBlendChannelDeltas(
local: DeformerChannels,
deltas: DeformerBlendChannelDeltas?,
): DeformerChannels {
if (deltas == null) {
return local
}
return DeformerChannels(
(local.opacity + deltas.opacity).coerceIn(0f, 1f),
ColorRgb(
local.multiplyColor.red + deltas.multiplyColor.red,
local.multiplyColor.green + deltas.multiplyColor.green,
local.multiplyColor.blue + deltas.multiplyColor.blue,
).coerceToUnit(),
ColorRgb(
local.screenColor.red + deltas.screenColor.red,
local.screenColor.green + deltas.screenColor.green,
local.screenColor.blue + deltas.screenColor.blue,
).coerceToUnit(),
)
}
@@ -0,0 +1,420 @@
package org.umamo.render.eval
import org.umamo.runtime.eval.warpControlPointsAt
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PuppetModel
import kotlin.math.abs
import kotlin.math.max
import kotlin.math.sqrt
/** Newton iteration cap for the warp inverse; drag-sized motion converges in a handful of steps. */
private const val WARP_INVERSE_MAX_ITERATIONS = 20
/** Finite-difference step (in the lattice's normalized UV units) for the warp inverse's Jacobian. */
private const val WARP_INVERSE_JACOBIAN_STEP = 1e-4f
/** Damping clamp on one Newton step (UV units), so an extrapolation seam cannot fling the estimate. */
private const val WARP_INVERSE_MAX_STEP = 0.5f
/**
* Iteration cap for the per-vertex reach-uncapped Newton in the world-rigid inverse. Higher than the
* damped [WARP_INVERSE_MAX_ITERATIONS] because there is no per-step clamp: a far target is reached by
* full Newton steps that re-anchor the Jacobian, converging in a handful once the estimate lands in the
* lattice's far-field affine region; the cap only bounds a pathological (folded / multivalued) case.
*/
private const val RIGID_INVERSE_MAX_ITERATIONS = 24
/**
* Maps between a drawable's local mesh space and the evaluator's world space at one fixed pose - the
* `DeformedGeometry.worldPositions` space the viewport camera and picker use. Local space is whatever
* the drawable's `DrawableMesh.positions` are stored in: model space for a direct (deformer-less)
* drawable, the parent's normalized lattice UV for a warp child, the parent's affine frame for a
* rotation child. The parent transform here is the FULLY COMPOSED chain (`buildDeformerWorlds` bakes
* every ancestor in), so both directions are a single transform, never a chain walk.
*
* The Edit-mode gizmo is the intended caller: it projects the active drawable's local shape to world
* for drawing and hit-testing (forward), and converts a world-space drag back into local vertex
* positions to write into the model (inverse).
*
* ドロウアブルのローカル座標と評価器のワールド座標を、固定ポーズで相互変換する。
*/
class DrawableSpaceMapping internal constructor(
private val parentWorld: DeformerWorld?,
) {
/**
* Maps interleaved (x, y) local positions to world positions: the composed parent transform (or a
* pass-through for a direct drawable) followed by the renderer's Y negation - the exact composition
* of `deformMeshWorldFromCorners`.
*
* @param FloatArray local The interleaved local positions.
* @return FloatArray The interleaved world positions (a new array).
*/
fun localToWorld(local: FloatArray): FloatArray {
val world = FloatArray(local.size)
val vertexCount = local.size / 2
for (vertexIndex in 0 until vertexCount) {
if (parentWorld != null) {
parentWorld.apply(local[vertexIndex * 2], local[vertexIndex * 2 + 1], world, vertexIndex * 2)
} else {
world[vertexIndex * 2] = local[vertexIndex * 2]
world[vertexIndex * 2 + 1] = local[vertexIndex * 2 + 1]
}
world[vertexIndex * 2 + 1] = -world[vertexIndex * 2 + 1]
}
return world
}
/**
* Maps world positions back to local positions for the given vertex [indices], leaving every other
* vertex at its [seedLocal] value. The rotation affine inverts in closed form; the warp lattice
* inverts by damped Newton iteration on the forward transform, seeded per vertex from [seedLocal]
* (the vertex's own original UV), keeping the best estimate when it cannot converge - a vertex
* sticks rather than jumps. A degenerate transform (zero determinant) keeps the seed.
*
* @param FloatArray world The interleaved world positions to invert.
* @param FloatArray seedLocal The local positions to start from (and to keep for untouched vertices).
* @param Set<Int> indices The vertex indices to solve.
* @return FloatArray The interleaved local positions (a new array).
*/
fun worldToLocal(world: FloatArray, seedLocal: FloatArray, indices: Set<Int>): FloatArray {
val local = seedLocal.copyOf()
val scratch = FloatArray(2)
for (vertexIndex in indices) {
val coordIndex = vertexIndex * 2
if (coordIndex + 1 >= world.size || coordIndex + 1 >= local.size) {
continue
}
// Un-negate Y first: the parent transforms operate in the pre-negate model space.
val targetX = world[coordIndex]
val targetY = -world[coordIndex + 1]
when (parentWorld) {
null -> {
local[coordIndex] = targetX
local[coordIndex + 1] = targetY
}
is RotationWorld -> invertRotation(parentWorld, targetX, targetY, local, coordIndex)
is WarpWorld -> invertWarp(parentWorld, targetX, targetY, local, coordIndex, scratch)
}
}
return local
}
/**
* Maps world positions back to local for the given vertex [indices] with a per-vertex EXACT inverse,
* leaving every other vertex at its [seedLocal] value. A direct parent inverts by pure Y un-negation and
* a rotation parent by its closed-form affine inverse (both one step); a warp parent inverts each vertex
* independently by a reach-uncapped Newton ([invertWarpUncapped]) seeded from its own rest UV, so every
* vertex lands on its own world target - the mesh stays rigid in world space (no squish), which the
* shared-Jacobian linearizations cannot achieve on a curved cage.
*
* Seeding each warp vertex from its rest UV keeps neighbours converging to nearby pre-images, so the
* result stays coherent (no scatter) wherever the forward map is injective. Where a target sits in a
* folded / multivalued extrapolation region the Newton keeps its best estimate near the seed rather than
* flinging - so a truly unreachable vertex lags instead of boiling. Not capping the per-step reach
* (unlike [invertWarp]) is what lets a large grab follow instead of pinning / ovalizing; the risk traded
* back is that a strongly non-injective cage can still scatter far outside the lattice (the reason the
* shared-Jacobian inverse exists).
*
* The warp tolerance and scratch are hoisted out of the vertex loop (constant per mapping), and the
* Newton early-exits the moment a vertex converges, so the whole-selection Object-mode grab (hundreds of
* warp vertices per drawable, over many drawables) stays interactive. A degenerate Jacobian (a
* zero-scale deformer) keeps the seed.
*
* @param FloatArray world The interleaved transformed world targets to invert.
* @param FloatArray seedLocal The rest local coords (per-vertex Newton seed; kept for untouched vertices).
* @param FloatArray worldRest The frozen pre-transform world positions (unused here; kept for the shared
* caller signature and the linearized-inverse contract).
* @param Set<Int> indices The vertex indices to solve.
* @return FloatArray The interleaved local positions (a new array).
*/
fun worldToLocalLinearized(world: FloatArray, seedLocal: FloatArray, worldRest: FloatArray, indices: Set<Int>): FloatArray {
val local = seedLocal.copyOf()
when (parentWorld) {
null -> {
for (vertexIndex in indices) {
val coordIndex = vertexIndex * 2
if (coordIndex + 1 >= world.size || coordIndex + 1 >= local.size) {
continue
}
// Un-negate Y: the parent frame is the pre-negate model space.
local[coordIndex] = world[coordIndex]
local[coordIndex + 1] = -world[coordIndex + 1]
}
}
is RotationWorld -> {
for (vertexIndex in indices) {
val coordIndex = vertexIndex * 2
if (coordIndex + 1 >= world.size || coordIndex + 1 >= local.size) {
continue
}
invertRotation(parentWorld, world[coordIndex], -world[coordIndex + 1], local, coordIndex)
}
}
is WarpWorld -> {
// Constant per mapping, so it's computed once here rather than per vertex.
val toleranceSquared = warpInverseToleranceSquared(parentWorld.cp)
val scratch = FloatArray(2)
for (vertexIndex in indices) {
val coordIndex = vertexIndex * 2
if (coordIndex + 1 >= world.size || coordIndex + 1 >= local.size) {
continue
}
invertWarpUncapped(parentWorld, world[coordIndex], -world[coordIndex + 1], local, coordIndex, toleranceSquared, scratch)
}
}
}
return local
}
/**
* Reach-uncapped world-rigid inverse of the warp lattice: solves `warpApply(u, v) = (targetX, targetY)`
* from the seed already in `local[coordIndex]`,`local[coordIndex+1]`, writing the best estimate back.
* Identical to [invertWarp] except it has no per-step damping clamp, so a full Newton step reaches a
* far target instead of pinning at [WARP_INVERSE_MAX_STEP], which keeps the mesh from pinning /
* ovalizing on a big grab. Allocation-free (reuses [scratch]) and early-exits at [toleranceSquared], so
* it stays cheap for a whole-selection Object-mode grab; [toleranceSquared] is passed in because it is
* constant per lattice.
*
* @param WarpWorld warp The baked world lattice.
* @param Float targetX The pre-negate world x to invert.
* @param Float targetY The pre-negate world y to invert.
* @param FloatArray local The output array, seeded with the starting UV at [coordIndex].
* @param Int coordIndex Index of the u slot in [local].
* @param Float toleranceSquared The squared convergence tolerance for this lattice.
* @param FloatArray scratch A reusable 2-slot scratch for forward evaluations.
*/
private fun invertWarpUncapped(warp: WarpWorld, targetX: Float, targetY: Float, local: FloatArray, coordIndex: Int, toleranceSquared: Float, scratch: FloatArray) {
var currentU = local[coordIndex]
var currentV = local[coordIndex + 1]
var bestU = currentU
var bestV = currentV
var bestErrorSquared = Float.MAX_VALUE
for (iteration in 0 until RIGID_INVERSE_MAX_ITERATIONS) {
warpApply(warp.cp, warp.cols, warp.rows, warp.bilinear, currentU, currentV, scratch, 0)
val residualX = scratch[0] - targetX
val residualY = scratch[1] - targetY
val errorSquared = residualX * residualX + residualY * residualY
if (errorSquared < bestErrorSquared) {
bestErrorSquared = errorSquared
bestU = currentU
bestV = currentV
}
if (errorSquared <= toleranceSquared) {
break
}
warpApply(warp.cp, warp.cols, warp.rows, warp.bilinear, currentU + WARP_INVERSE_JACOBIAN_STEP, currentV, scratch, 0)
val dxDu = (scratch[0] - (residualX + targetX)) / WARP_INVERSE_JACOBIAN_STEP
val dyDu = (scratch[1] - (residualY + targetY)) / WARP_INVERSE_JACOBIAN_STEP
warpApply(warp.cp, warp.cols, warp.rows, warp.bilinear, currentU, currentV + WARP_INVERSE_JACOBIAN_STEP, scratch, 0)
val dxDv = (scratch[0] - (residualX + targetX)) / WARP_INVERSE_JACOBIAN_STEP
val dyDv = (scratch[1] - (residualY + targetY)) / WARP_INVERSE_JACOBIAN_STEP
val determinant = dxDu * dyDv - dxDv * dyDu
if (abs(determinant) < 1e-12f) {
break
}
currentU += (-residualX * dyDv + dxDv * residualY) / determinant
currentV += (-residualY * dxDu + dyDu * residualX) / determinant
}
local[coordIndex] = bestU
local[coordIndex + 1] = bestV
}
}
/**
* Builds the local<->world mapping for [drawableId] at the given pose, resolving parameters with the
* evaluator's fallback (`parameters[id] ?: parameter.default ?: 0`). Returns null when the drawable
* does not exist or its parent deformer's world transform cannot be built (a hidden ancestor) - the
* drawable is not on screen, so there is nothing to map onto.
*
* @param PuppetModel model The rig.
* @param Map parameters Parameter id -> value (partial; the rest default).
* @param DrawableId drawableId The drawable to map.
* @return DrawableSpaceMapping? The mapping, or null when unmappable.
*/
fun drawableSpaceMapping(model: PuppetModel, parameters: Map<ParameterId, Float>, drawableId: DrawableId): DrawableSpaceMapping? {
val drawable = model.drawables.firstOrNull { it.id == drawableId } ?: return null
val parentDeformerId = drawable.parentDeformerId ?: return DrawableSpaceMapping(null)
val defaults = model.parameters.associate { it.id to it.default }
val paramValue: (ParameterId) -> Float = { parameters[it] ?: defaults[it] ?: 0f }
val parentWorld = buildDeformerWorlds(model.deformers, paramValue)[parentDeformerId] ?: return null
return DrawableSpaceMapping(parentWorld)
}
/**
* Maps a warp deformer's lattice-local control points to viewport world space the same way
* [drawableSpaceMapping] maps a child mesh: through the warp's PARENT chain, then the renderer's Y
* negation. Null when the warp is missing or its parent is hidden at this pose.
*
* @param PuppetModel model The rig.
* @param Map parameters Parameter id -> value (partial; the rest default).
* @param org.umamo.runtime.model.DeformerId deformerId The warp to map.
* @return DrawableSpaceMapping? The mapping, or null when unmappable.
*/
fun warpLatticeSpaceMapping(
model: PuppetModel,
parameters: Map<ParameterId, Float>,
deformerId: DeformerId,
): DrawableSpaceMapping? {
val deformer = model.deformers.firstOrNull { it.id == deformerId } as? Deformer.Warp ?: return null
val parentDeformerId = deformer.parent ?: return DrawableSpaceMapping(null)
val defaults = model.parameters.associate { it.id to it.default }
val paramValue: (ParameterId) -> Float = { parameters[it] ?: defaults[it] ?: 0f }
val parentWorld = buildDeformerWorlds(model.deformers, paramValue)[parentDeformerId] ?: return null
return DrawableSpaceMapping(parentWorld)
}
/**
* The warp's blended lattice-local control points at [parameters], or null when the warp is unkeyed /
* hidden. Same space [WarpLatticeForm] stores - parent-local, before the parent chain and Y flip.
*
* @param PuppetModel model The rig.
* @param Map parameters Parameter id -> value.
* @param DeformerId deformerId The warp.
* @return FloatArray? Interleaved local control points, or null.
*/
fun warpLatticeLocalAt(
model: PuppetModel,
parameters: Map<ParameterId, Float>,
deformerId: DeformerId,
): FloatArray? {
val deformer = model.deformers.firstOrNull { it.id == deformerId } as? Deformer.Warp ?: return null
val defaults = model.parameters.associate { it.id to it.default }
val paramValue: (ParameterId) -> Float = { parameters[it] ?: defaults[it] ?: 0f }
return warpControlPointsAt(deformer.geometryGrid, paramValue)?.copyOf()
}
/**
* The drawable's blended LOCAL posed positions at the given pose - base plus the multilinear keyform
* blend, before any parent deformer. This is the local shape the renderer feeds the deformer chain, so
* a display that projects it through [DrawableSpaceMapping.localToWorld] lands exactly on the rendered
* art at ANY pose (including between keys, where a single cell's deltas would not).
*
* @param PuppetModel model The rig.
* @param Map parameters Parameter id -> value (partial; the rest default).
* @param DrawableId drawableId The drawable to sample.
* @return FloatArray? The interleaved local posed positions, or null when the drawable / mesh / grid is
* missing or the pose hides it (out of range).
*/
fun drawableLocalPosed(model: PuppetModel, parameters: Map<ParameterId, Float>, drawableId: DrawableId): FloatArray? {
val drawable = model.drawables.firstOrNull { it.id == drawableId } ?: return null
val mesh = drawable.mesh ?: return null
// An unkeyed drawable sits at its rest mesh, which is exactly the state a rigger needs the gizmo to
// show - returning null here would hide the vertices of the drawable they are about to key.
val grid = drawable.geometryGrid ?: return mesh.positions.copyOf()
val defaults = model.parameters.associate { it.id to it.default }
val paramValue: (ParameterId) -> Float = { parameters[it] ?: defaults[it] ?: 0f }
return sampleMeshLocal(grid, mesh.positions, paramValue)
}
/**
* Closed-form inverse of the baked rotation affine `x' = c12*x + c15*y + ox, y' = c14*x + c13*y + oy`,
* writing the solved local point to `local[coordIndex]`,`local[coordIndex+1]`. A near-zero determinant
* (a zero-scale deformer) keeps the seed untouched.
*
* @param RotationWorld rotation The baked world affine.
* @param Float targetX The pre-negate world x to invert.
* @param Float targetY The pre-negate world y to invert.
* @param FloatArray local The output array (seeded; written only on success).
* @param Int coordIndex Index of the x slot in [local].
*/
private fun invertRotation(rotation: RotationWorld, targetX: Float, targetY: Float, local: FloatArray, coordIndex: Int) {
val xform = rotation.xform
val determinant = xform.c12 * xform.c13 - xform.c15 * xform.c14
if (abs(determinant) < 1e-12f) {
return
}
val relativeX = targetX - xform.ox
val relativeY = targetY - xform.oy
local[coordIndex] = (relativeX * xform.c13 - xform.c15 * relativeY) / determinant
local[coordIndex + 1] = (xform.c12 * relativeY - xform.c14 * relativeX) / determinant
}
/**
* Damped Newton inverse of the warp lattice: solves `warpApply(u, v) = target` starting from the seed
* already in `local[coordIndex]`,`local[coordIndex+1]`, using a finite-difference Jacobian. Writes the
* best estimate found (by residual) back into [local]; the tolerance scales with the lattice's control
* point extent so convergence means sub-art-pixel accuracy at any canvas size.
*
* @param WarpWorld warp The baked world lattice.
* @param Float targetX The pre-negate world x to invert.
* @param Float targetY The pre-negate world y to invert.
* @param FloatArray local The output array, seeded with the starting UV.
* @param Int coordIndex Index of the u slot in [local].
* @param FloatArray scratch A reusable 2-slot scratch for forward evaluations.
*/
private fun invertWarp(warp: WarpWorld, targetX: Float, targetY: Float, local: FloatArray, coordIndex: Int, scratch: FloatArray) {
val toleranceSquared = warpInverseToleranceSquared(warp.cp)
var currentU = local[coordIndex]
var currentV = local[coordIndex + 1]
var bestU = currentU
var bestV = currentV
var bestErrorSquared = Float.MAX_VALUE
for (iteration in 0 until WARP_INVERSE_MAX_ITERATIONS) {
warpApply(warp.cp, warp.cols, warp.rows, warp.bilinear, currentU, currentV, scratch, 0)
val residualX = scratch[0] - targetX
val residualY = scratch[1] - targetY
val errorSquared = residualX * residualX + residualY * residualY
if (errorSquared < bestErrorSquared) {
bestErrorSquared = errorSquared
bestU = currentU
bestV = currentV
}
if (errorSquared <= toleranceSquared) {
break
}
warpApply(warp.cp, warp.cols, warp.rows, warp.bilinear, currentU + WARP_INVERSE_JACOBIAN_STEP, currentV, scratch, 0)
val dxDu = (scratch[0] - (residualX + targetX)) / WARP_INVERSE_JACOBIAN_STEP
val dyDu = (scratch[1] - (residualY + targetY)) / WARP_INVERSE_JACOBIAN_STEP
warpApply(warp.cp, warp.cols, warp.rows, warp.bilinear, currentU, currentV + WARP_INVERSE_JACOBIAN_STEP, scratch, 0)
val dxDv = (scratch[0] - (residualX + targetX)) / WARP_INVERSE_JACOBIAN_STEP
val dyDv = (scratch[1] - (residualY + targetY)) / WARP_INVERSE_JACOBIAN_STEP
val determinant = dxDu * dyDv - dxDv * dyDu
if (abs(determinant) < 1e-12f) {
break
}
var stepU = (-residualX * dyDv + dxDv * residualY) / determinant
var stepV = (-residualY * dxDu + dyDu * residualX) / determinant
val stepLength = sqrt(stepU * stepU + stepV * stepV)
if (stepLength > WARP_INVERSE_MAX_STEP) {
val damping = WARP_INVERSE_MAX_STEP / stepLength
stepU *= damping
stepV *= damping
}
currentU += stepU
currentV += stepV
}
local[coordIndex] = bestU
local[coordIndex + 1] = bestV
}
/**
* The squared convergence tolerance for the warp inverse, scaled to the lattice's control-point extent
* (1e-5 of the larger bounding-box span, floored well above float noise).
*
* @param FloatArray cp The lattice's world control points, interleaved x,y.
* @return Float The squared world-distance tolerance.
*/
private fun warpInverseToleranceSquared(cp: FloatArray): Float {
var minX = Float.MAX_VALUE
var maxX = -Float.MAX_VALUE
var minY = Float.MAX_VALUE
var maxY = -Float.MAX_VALUE
val pointCount = cp.size / 2
for (pointIndex in 0 until pointCount) {
val x = cp[pointIndex * 2]
val y = cp[pointIndex * 2 + 1]
minX = minOf(minX, x)
maxX = maxOf(maxX, x)
minY = minOf(minY, y)
maxY = maxOf(maxY, y)
}
val span = max(maxX - minX, maxY - minY)
val tolerance = max(1e-5f * span, 1e-6f)
return tolerance * tolerance
}
@@ -0,0 +1,21 @@
package org.umamo.render.eval
import org.umamo.runtime.model.Keyform
/**
* Multilinear blend for a single parameter axis: `base + Σ wᵢ·Δᵢ`.
*
* A 1-D isolation of the blend math also used, generalized to N dimensions, by the real keyform-grid
* blend in [blendLocalFromCorners]. Kept as a free function so it's trivially testable on its own.
*
* 単一パラメータ軸の多重線形ブレンド。実 N 次元評価の 1 次元プレースホルダ。
*/
fun blend(base: FloatArray, keyforms: List<Pair<Float, Keyform>>): FloatArray {
val result = base.copyOf()
for ((weight, keyform) in keyforms) {
for (i in result.indices) {
result[i] += weight * keyform.delta[i]
}
}
return result
}
@@ -0,0 +1,105 @@
package org.umamo.render.eval
import org.umamo.runtime.eval.WeightedCell
import org.umamo.runtime.eval.cellsByLinearIndex
import org.umamo.runtime.eval.gridCorners
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshDeltaForm
import org.umamo.runtime.model.ParameterId
/*
* Grid sampling over the runtime's shared multilinear corner selection. The corner selection,
* bracket, and pose-sampling primitives (bindBracket / gridCorners / cellsByLinearIndex /
* plus the blend-shape default-pose reference helpers) live in
* org.umamo.runtime.eval (KeyformGridSampling.kt) so Moc3Import shares them - see the note there.
* This file keeps the render-side blends built on top of them.
*/
/**
* Samples an art-mesh keyform grid into local (parent-deformer-space) vertex positions:
* `base + Σ wᵢ·Δᵢ` (interleaved x,y). Because the corner weights sum to 1, this equals the
* Umamo C++ Runtime's absolute-keyform blend. Returns null when the mesh is hidden at
* these parameters.
*
* @param KeyformGrid grid The mesh's keyform grid.
* @param FloatArray base The mesh's rest-pose positions.
* @param Function paramValue Current value for a given parameter id.
* @return FloatArray? The local vertex positions, or null when hidden.
*/
internal fun sampleMeshLocal(
grid: KeyformGrid<MeshDeltaForm>,
base: FloatArray,
paramValue: (ParameterId) -> Float,
): FloatArray? {
val corners = gridCorners(grid, paramValue) ?: return null
return blendLocalFromCorners(grid, base, corners)
}
/**
* Blends a mesh's local positions from precomputed corners: `base + Σ wᵢ·Δᵢ`. Splitting corner selection
* out of [sampleMeshLocal] lets `preparePose` compute the weights once - backend-neutrally - and feed both
* the CPU apply path and (later) the GPU shader the same corner set.
*
* A null [grid] is an UNKEYED drawable, not an error: it contributes no deltas, so the result is the rest
* mesh. An unkeyed drawable is a normal state - a freshly created one, or one whose last keyform axis was
* just removed - and it has to render, or the rigger cannot see the thing they are about to key.
*
* @param KeyformGrid? grid The mesh's keyform grid, or null when the drawable is unkeyed.
* @param FloatArray base The mesh's rest-pose positions (interleaved x,y).
* @param List<WeightedCell> corners The active keyform corners + weights (from [gridCorners]).
* @return FloatArray The blended local positions (interleaved x,y).
*/
internal fun blendLocalFromCorners(grid: KeyformGrid<MeshDeltaForm>?, base: FloatArray, corners: List<WeightedCell>): FloatArray {
val cells = if (grid != null) cellsByLinearIndex(grid) else emptyMap()
val out = base.copyOf()
for (corner in corners) {
val delta = cells[corner.linearIndex]?.form?.positionDeltas ?: continue
val count = minOf(out.size, delta.size)
for (coordIndex in 0 until count) {
out[coordIndex] += corner.weight * delta[coordIndex]
}
}
return out
}
/**
* An isolated part's pose-blended composite channels - what the renderer applies when it
* composites the part's subtree layer back into the scene.
*
* @property Float opacity The composite opacity (0..1).
* @property ColorRgb multiplyColor The composite multiply color.
* @property ColorRgb screenColor The composite screen color.
*/
internal class PartRenderState(
val opacity: Float,
val multiplyColor: ColorRgb,
val screenColor: ColorRgb,
)
/**
* Evaluates a direct (deformer-less) art mesh into world positions: the keyform-blended local
* vertices with the Y component negated (`vp = (x, −y)`; only Y flips). This matches the CMO3/MOC3
* world-space convention, which is Y-down relative to the local mesh space Umamo blends in - required for
* preview parity with the official Cubism Editor. Returns null when the mesh is hidden at these
* parameters. Deformer-parented meshes go through the cascade instead, which applies the same negation
* after composing through the parent transform.
*
* @param KeyformGrid grid The mesh's keyform grid.
* @param FloatArray base The mesh's rest-pose positions (interleaved x,y).
* @param Function paramValue Current value for a given parameter id.
* @return FloatArray? World positions (interleaved x,y), or null when hidden.
*/
internal fun evalDirectMeshWorld(
grid: KeyformGrid<MeshDeltaForm>,
base: FloatArray,
paramValue: (ParameterId) -> Float,
): FloatArray? {
val world = sampleMeshLocal(grid, base, paramValue) ?: return null
var yIndex = 1
while (yIndex < world.size) {
world[yIndex] = -world[yIndex]
yIndex += 2
}
return world
}
@@ -0,0 +1,147 @@
package org.umamo.render.eval
import org.umamo.runtime.model.DEFAULT_DRAW_ORDER
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.PartComposite
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.RenderDrawable
import org.umamo.runtime.model.RenderGroup
import org.umamo.runtime.model.RenderNode
/**
* A node of the resolved per-pose render plan: the back-to-front order WITH the isolated group
* boundaries preserved. A plain Grouped part needs no boundary (its children flatten into the
* surrounding order, exactly one slot's worth) - only an ISOLATED group becomes a node, because
* the renderer must know which span of drawables renders into a layer and composites back as one
* unit. Nesting is direct: a composite node's children may contain further composite nodes.
*/
sealed interface RenderPlanNode
/** A drawable drawn directly into the current render target. */
class RenderPlanDrawable(val id: DrawableId) : RenderPlanNode
/**
* An isolated part's subtree: render [children] (back-to-front) into a layer, then composite that
* layer back as one unit using [composite]'s blend modes/masks and the pose's blended channels
* (PoseDeformInputs.partCompositeStates keyed by [partId]).
*/
class RenderPlanComposite(
val partId: PartId,
val composite: PartComposite,
val children: List<RenderPlanNode>,
) : RenderPlanNode
/**
* The per-pose render plan over the draw-order group tree: [renderOrder]'s hierarchical sort with
* isolated group boundaries kept as [RenderPlanComposite] nodes. Plain groups flatten away
* exactly as before - `renderOrder` IS this plan flattened, so the two can never disagree.
*
* @param RenderGroup root The draw-order group tree root (`PuppetModel.renderRoot`).
* @param Map<DrawableId,Float> drawOrder Blended draw order per drawable (missing → the Cubism default).
* @param Map<PartId,Float> partDrawOrders Blended per-group part draw order (missing → the static value).
* @return List<RenderPlanNode> The plan nodes, back-to-front.
*/
fun renderPlan(
root: RenderGroup,
drawOrder: Map<DrawableId, Float>,
partDrawOrders: Map<PartId, Float> = emptyMap(),
): List<RenderPlanNode> {
fun sortKey(node: RenderNode): Int =
when (node) {
is RenderDrawable -> ((drawOrder[node.id] ?: DEFAULT_DRAW_ORDER.toFloat()) + 0.001f).toInt()
is RenderGroup -> node.partId?.let { partDrawOrders[it] }?.let { (it + 0.001f).toInt() } ?: node.drawOrder
}
fun emit(group: RenderGroup, into: ArrayList<RenderPlanNode>) {
for (child in group.children.sortedBy(::sortKey)) {
when (child) {
is RenderDrawable -> into.add(RenderPlanDrawable(child.id))
is RenderGroup -> {
val composite = child.composite
val partId = child.partId
if (composite != null && partId != null) {
val subtree = ArrayList<RenderPlanNode>()
emit(child, subtree)
into.add(RenderPlanComposite(partId, composite, subtree))
} else {
emit(child, into)
}
}
}
}
}
val nodes = ArrayList<RenderPlanNode>()
emit(root, nodes)
return nodes
}
/**
* Flattens a render plan to its drawables in back-to-front order (composite boundaries dropped).
*
* @param List<RenderPlanNode> nodes The plan nodes.
* @return List<DrawableId> The drawables, back-to-front.
*/
fun flattenRenderPlan(nodes: List<RenderPlanNode>): List<DrawableId> {
val result = ArrayList<DrawableId>()
fun walk(node: RenderPlanNode) {
when (node) {
is RenderPlanDrawable -> result.add(node.id)
is RenderPlanComposite -> node.children.forEach(::walk)
}
}
nodes.forEach(::walk)
return result
}
/**
* The back-to-front paint order for one pose, computed hierarchically over the draw-order group tree.
* Within each [RenderGroup] the children are stably sorted by an int sort key (a [RenderDrawable] by
* its own quantised draw order, a sub-[RenderGroup] by the part's draw order), then emitted depth-first.
* So a drawable's draw order only sorts it among its group siblings, and a "Group by Draw Order" part
* moves as a unit - a child can't escape the group's slot.
*
* A group-less model is one flat group of all drawables, so this reduces exactly to [paintOrder]'s global
* sort. Quantisation (`+0.001`→int) matches the Umamo C++ runtime and de-noises tied float draw orders
* (see [paintOrder]).
*
* A sub-group's key is its part draw order, which can itself be parameter-driven ([partDrawOrders])
* - blended per pose, quantised the same way; missing → the group's static [RenderGroup.drawOrder].
* So whole groups swap front/back as their controlling parameters move.
*
* @param RenderGroup root The draw-order group tree root (`PuppetModel.renderRoot`).
* @param Map<DrawableId,Float> drawOrder Blended draw order per drawable (missing → the Cubism default).
* @param Map<PartId,Float> partDrawOrders Blended per-group part draw order (missing → the static value).
* @return List<DrawableId> The drawables in back-to-front paint order.
*/
fun renderOrder(
root: RenderGroup,
drawOrder: Map<DrawableId, Float>,
partDrawOrders: Map<PartId, Float> = emptyMap(),
): List<DrawableId> = flattenRenderPlan(renderPlan(root, drawOrder, partDrawOrders))
/**
* The back-to-front paint order for one pose. [baseOrder] is the model's parts-tree (panel) drawable
* order - already back-to-front when draw orders are equal - and this stably re-sorts it by the
* per-drawable blended [drawOrder], the primary key. A higher draw order paints later (in front) across
* the whole model regardless of part; equal draw orders keep [baseOrder]. This mirrors how the Cubism
* editor stacks drawables (drawOrder first, the parts tree breaking ties).
*
* Quantise to int before sorting: (`drawDrawOrders[i] = (int)(0.001f + drawOrder)`).
* Draw order is authored as an integer (0-1000, default 500); the multilinear keyform blend
* `Σ wᵢ·orderᵢ` only lands near an integer (float-summation gives e.g. 499.99997 vs 500.00003), so
* sorting the raw float reshuffles drawables that should be tied - a sub-ULP-noise reorder that makes a
* coincident-order drawable (e.g. a masked head shadow at 500) flicker in front of the face at the
* parameter values where the noise crosses. Flooring `+0.001` collapses the noise to a true tie so the
* stable sort preserves [baseOrder]; the `+0.001` rescues a value sitting just below its intended integer.
*
* Because draw order rides on the keyform, it is param-dependent - pass the [DeformedGeometry.drawOrder]
* for the current pose, so a parameter that animates stacking reorders correctly per frame.
*
* @param List<DrawableId> baseOrder The model's drawables, in parts-tree back-to-front order.
* @param Map<DrawableId,Float> drawOrder Blended draw order per drawable (missing → the Cubism default).
* @return List<DrawableId> The drawables in back-to-front paint order.
*/
fun paintOrder(baseOrder: List<DrawableId>, drawOrder: Map<DrawableId, Float>): List<DrawableId> =
baseOrder.sortedBy { ((drawOrder[it] ?: DEFAULT_DRAW_ORDER.toFloat()) + 0.001f).toInt() }
@@ -0,0 +1,131 @@
package org.umamo.render.glsl
// The canvas backdrop's GLSL - the world-aligned grid and the world-origin axis lines.
//
// These were previously hand-copied between the desktop and Android backends, identical but for the
// preamble, with nothing pinning the two together. They had already begun to drift: the Android copies
// had silently lost three of the explanatory comments. Only comments so far, which is precisely why
// merging them now was worth doing - the next divergence would have been in the math, and nothing would
// have caught it.
//
// Metal shares none of this; see GlslDialect.
/**
* The full-screen pass's vertex shader: one oversized triangle covering the viewport.
*
* No vertex buffer - the three corners are derived from `gl_VertexID`, so no attributes are needed (and
* on a core profile, only an empty VAO).
*
* 頂点バッファ無しの全画面パス。三角形の頂点は gl_VertexID から生成する。
*
* @param GlslDialect dialect The target flavor.
* @return String The ready-to-compile source.
*/
internal fun gridVertexShader(dialect: GlslDialect): String =
glslHeader(dialect) +
"""
void main() {
// id 0 -> (-1,-1), 1 -> (-1,3), 2 -> (3,-1): one oversized triangle covering the viewport.
gl_Position = vec4(float(gl_VertexID / 2) * 4.0 - 1.0, float(gl_VertexID % 2) * 4.0 - 1.0, 0.0, 1.0);
}
""".trimIndent()
/**
* The world-aligned grid backdrop's fragment shader.
*
* Each fragment recovers its world position by inverting the same world-to-NDC affine the puppet is
* projected through, then draws anti-aliased lines wherever that world coord is near a multiple of the
* major or minor spacing. Colors and spacings arrive as uniforms so the backdrop follows the editor
* theme and the per-document grid config. Opaque, so it both clears and paints in one pass.
*
* ワールド整列グリッド。worldToNdc を逆変換して各フラグメントのワールド座標を求め、主線・副線を描く。
*
* @param GlslDialect dialect The target flavor.
* @return String The ready-to-compile source.
*/
internal fun gridFragmentShader(dialect: GlslDialect): String =
glslHeader(dialect) +
"""
out vec4 fragColor;
uniform vec2 viewportSize;
uniform vec4 worldToNdc; // scaleX, scaleY, offsetX, offsetY
uniform vec2 majorSpacing; // world units per major cell, per axis
uniform float subdivisions; // minor lines per major cell
uniform float lineWidthPx; // line half-width in framebuffer pixels
uniform vec3 backgroundColor;
uniform vec3 majorColor;
uniform vec3 minorColor;
uniform vec2 gridOrigin; // world point a major line passes through (the world axes)
// Anti-aliased line coverage for a coordinate on a lattice of the given spacing. cellDist is the
// fractional distance to the nearest line in cell units (0 on a line, 0.5 mid-cell); scaling it by
// spacing / worldPerPixel converts it to framebuffer pixels, so the band stays a constant on-screen
// width at any zoom - derived from the affine, not GLSL derivatives, so it is driver-independent.
float lineCoverage(vec2 world, vec2 spacing, vec2 worldPerPixel) {
vec2 cell = world / spacing;
vec2 cellDist = abs(fract(cell - 0.5) - 0.5);
vec2 pixelDist = cellDist * spacing / worldPerPixel;
float nearestPx = min(pixelDist.x, pixelDist.y);
return 1.0 - smoothstep(0.0, lineWidthPx, nearestPx);
}
void main() {
vec2 ndc = (gl_FragCoord.xy / viewportSize) * 2.0 - 1.0;
vec2 world = (ndc - worldToNdc.zw) / worldToNdc.xy;
// World units per framebuffer pixel, from the affine: an NDC span of 2 covers viewportSize pixels
// and worldToNdc.xy world units per NDC unit. abs() drops the Y-axis flip sign.
vec2 worldPerPixel = abs((2.0 / viewportSize) / worldToNdc.xy);
// Anchor the lattice on the world origin (the axes), so a major line always crosses the axes
// rather than falling mid-cell for an arbitrary canvas size.
vec2 gridWorld = world - gridOrigin;
vec2 minorSpacing = majorSpacing / max(subdivisions, 1.0);
// Fade the minor lines out as their on-screen spacing collapses, so a zoomed-out grid does not
// alias into a solid wash: minorScreenPx is the minor spacing measured in framebuffer pixels.
vec2 minorScreenPx = minorSpacing / worldPerPixel;
float minorFade = clamp((min(minorScreenPx.x, minorScreenPx.y) - 4.0) / 8.0, 0.0, 1.0);
float minor = lineCoverage(gridWorld, minorSpacing, worldPerPixel) * minorFade;
float major = lineCoverage(gridWorld, majorSpacing, worldPerPixel);
vec3 color = mix(backgroundColor, minorColor, minor);
color = mix(color, majorColor, major);
fragColor = vec4(color, 1.0);
}
""".trimIndent()
/**
* One world-origin axis line's vertex shader.
*
* The two endpoints come from `gl_VertexID` (-1 / +1 along the line); the fixed coordinate and the
* orientation arrive as uniforms, so one program draws both axes.
*
* 軸線 1 本を描くパス。端点は gl_VertexID から生成し、固定座標と向きは uniform で受け取る。
*
* @param GlslDialect dialect The target flavor.
* @return String The ready-to-compile source.
*/
internal fun axisVertexShader(dialect: GlslDialect): String =
glslHeader(dialect) +
"""
uniform float linePositionNdc;
uniform float lineVertical;
void main() {
float along = float(gl_VertexID) * 2.0 - 1.0;
vec2 position = mix(vec2(along, linePositionNdc), vec2(linePositionNdc, along), lineVertical);
gl_Position = vec4(position, 0.0, 1.0);
}
""".trimIndent()
/**
* The axis line's fragment shader: a flat, opaque line color.
*
* @param GlslDialect dialect The target flavor.
* @return String The ready-to-compile source.
*/
internal fun axisFragmentShader(dialect: GlslDialect): String =
glslHeader(dialect) +
"""
out vec4 fragColor;
uniform vec3 lineColor;
void main() {
fragColor = vec4(lineColor, 1.0);
}
""".trimIndent()
@@ -0,0 +1,250 @@
package org.umamo.render.glsl
// The layer-composite program's GLSL, shared by the GL-family backends.
//
// The fragment shader is a line-for-line mirror of the pure reference in
// org.umamo.render.puppet.BlendMath (`compositeReference`) - the reference is the spec, the
// analytic GL tests compare read-back pixels against it, and any change must land in both.
// Formulas are the PUBLIC standards only (W3C Compositing and Blending Level 1, Porter-Duff,
// X Render conjoint/disjoint); nothing here is derived from the official Cubism SDK.
/**
* The composite vertex shader: an attribute-less full-screen triangle from `gl_VertexID`
* (draw 3 vertices with an empty VAO, like the grid backdrop).
*
* @param GlslDialect dialect The target flavor.
* @return String The ready-to-compile source.
*/
internal fun compositeVertexShader(dialect: GlslDialect): String =
glslHeader(dialect) +
"void main() {\n" +
" vec2 corner = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));\n" +
" gl_Position = vec4(corner * 2.0 - 1.0, 0.0, 1.0);\n" +
"}\n"
/**
* The composite fragment shader: samples the rendered layer and the destination snapshot at the
* fragment's screen position, applies the composite's channels (opacity, mask coverage,
* multiply/screen colors) to the layer, then computes the color blend B(Cb, Cs) and the alpha
* mode's Porter-Duff combination in-shader, writing premultiplied with blending DISABLED.
*
* The colorMode/alphaMode ints are the MOC3 packed halves (colorMode 0-17, alphaMode 0-4). The legacy
* "(Before 5.3)" Add/Multiply (colorMode 1/2) take the fixed-function premultiplied branch regardless of
* the alpha mode (they ignore Alpha blend, per BlendMath.compositeReference); Normal (0) does so only
* under Over.
*
* @param GlslDialect dialect The target flavor.
* @return String The ready-to-compile source.
*/
internal fun compositeFragmentShader(dialect: GlslDialect): String =
glslHeader(dialect) +
"""
out vec4 fragColor;
uniform sampler2D layerTexture;
uniform sampler2D destTexture;
uniform sampler2D maskTexture;
uniform vec2 screenTexSize;
uniform int colorMode;
uniform int alphaMode;
uniform float opacity;
uniform vec3 multiplyColor;
uniform vec3 screenColor;
uniform int useMask;
uniform int invertMask;
float lum3(vec3 c) {
return 0.3 * c.r + 0.59 * c.g + 0.11 * c.b;
}
vec3 clipColor3(vec3 c) {
float l = lum3(c);
float n = min(c.r, min(c.g, c.b));
float x = max(c.r, max(c.g, c.b));
if (n < 0.0) {
c = l + (c - l) * l / (l - n);
}
if (x > 1.0) {
c = l + (c - l) * (1.0 - l) / (x - l);
}
return c;
}
vec3 setLum3(vec3 c, float l) {
return clipColor3(c + (l - lum3(c)));
}
float sat3(vec3 c) {
return max(c.r, max(c.g, c.b)) - min(c.r, min(c.g, c.b));
}
vec3 setSat3(vec3 c, float s) {
float mn = min(c.r, min(c.g, c.b));
float mx = max(c.r, max(c.g, c.b));
return (mx > mn) ? (c - mn) * s / (mx - mn) : vec3(0.0);
}
float hardLightChannel(float base, float selector) {
float doubled = 2.0 * selector - 1.0;
return (selector <= 0.5) ? 2.0 * selector * base : base + doubled - base * doubled;
}
float softLightD(float x) {
return (x <= 0.25) ? ((16.0 * x - 12.0) * x + 4.0) * x : sqrt(x);
}
float blendChannel(float b, float s) {
if (colorMode == 1 || colorMode == 3 || colorMode == 4) {
//Additive Premultiplied, Additive, Additive Glow
return min(1.0, b + s);
}
if (colorMode == 2 || colorMode == 6) {
//Multiply
return b * s;
}
if (colorMode == 5) {
//Darken
return min(b, s);
}
if (colorMode == 7) {
//Color Burn
return (b >= 1.0) ? 1.0 : ((s <= 0.0) ? 0.0 : 1.0 - min(1.0, (1.0 - b) / s));
}
if (colorMode == 8) {
//Linear Burn
return max(0.0, b + s - 1.0);
}
if (colorMode == 9) {
//Lighten
return max(b, s);
}
if (colorMode == 10) {
//Screen
return b + s - b * s;
}
if (colorMode == 11) {
//Color Doge
return (b <= 0.0) ? 0.0 : ((s >= 1.0) ? 1.0 : min(1.0, b / (1.0 - s)));
}
if (colorMode == 12) {
//Overlay
return hardLightChannel(s, b);
}
if (colorMode == 13) {
//Soft Light
return (s <= 0.5) ? b - (1.0 - 2.0 * s) * b * (1.0 - b) : b + (2.0 * s - 1.0) * (softLightD(b) - b);
}
if (colorMode == 14) {
//Hard Light
return hardLightChannel(b, s);
}
if (colorMode == 15) {
//Linear Light
return clamp(b + 2.0 * s - 1.0, 0.0, 1.0);
}
return s;
}
vec3 blendColor3(vec3 Cb, vec3 Cs) {
if (colorMode == 16) {
return setLum3(setSat3(Cs, sat3(Cb)), lum3(Cb));
}
if (colorMode == 17) {
return setLum3(Cs, lum3(Cb));
}
return vec3(blendChannel(Cb.r, Cs.r), blendChannel(Cb.g, Cs.g), blendChannel(Cb.b, Cs.b));
}
void main() {
vec2 screenUv = gl_FragCoord.xy / screenTexSize;
vec4 layer = texture(layerTexture, screenUv);
vec4 dest = texture(destTexture, screenUv);
float layerScale = opacity;
if (useMask == 1) {
float coverage = texture(maskTexture, screenUv).a;
layerScale *= (invertMask == 1) ? (1.0 - coverage) : coverage;
}
layer *= layerScale;
float as = layer.a;
float ab = dest.a;
vec3 Cs = (as > 0.0) ? clamp(layer.rgb / as, 0.0, 1.0) : vec3(0.0);
Cs = Cs * multiplyColor;
Cs = Cs + screenColor - Cs * screenColor;
vec3 Cb = (ab > 0.0) ? clamp(dest.rgb / ab, 0.0, 1.0) : vec3(0.0);
vec4 outColor;
if (colorMode == 1 || colorMode == 2 || (alphaMode == 0 && colorMode == 0)) {
//Repremultiply after tinting.
vec3 srcPremul = Cs * as;
if (colorMode == 0) {
//Standard premultiplied source over.
outColor = vec4(srcPremul + dest.rgb * (1.0 - as), as + ab * (1.0 - as));
} else if (colorMode == 1) {
//Legacy Add
outColor = vec4(srcPremul + dest.rgb, ab);
} else {
//Legacy Multiply
outColor = vec4(srcPremul * dest.rgb + dest.rgb * (1.0 - as), ab);
}
} else {
float p0 = as * ab; //Uncorrelated (OVER/ATOP): w == ab, the same as W3C.
if (alphaMode == 3) {
//CONJOINT, maximal overlap.
p0 = min(as, ab);
} else if (alphaMode == 4) {
//DISJOINT, minimal overlap.
p0 = max(as + ab - 1.0, 0.0);
}
float w = (as > 0.0) ? p0 / as : 0.0;
//W3C Cs' = (1-w)*Cs + w*B(Cb, Cs). The specification's uncorrelated case has w = ab.
vec3 mixed = (1.0 - w) * Cs + w * blendColor3(Cb, Cs);
//Porter-Duff: co = as*Fa*Cs' + ab*Fb*Cb (premultiplied), ao = as*Fa + ab*Fb. The whole branch expands to p0*B + p1*Cs + p2*Cb with the KHR p-weights for the selected overlap mode.
float Fa;
float Fb;
if (alphaMode == 1) {
//SRC-ATOP: output keeps canvas alpha (ao = ab)
Fa = ab;
Fb = 1.0 - as;
} else if (alphaMode == 2) {
//DST-OUT: ao = ab*(1-as); Fa = 0 so 'mixed' is unused.
Fa = 0.0;
Fb = 1.0 - as;
} else if (alphaMode == 3) {
//CONJOINT: ao = max(as, ab)
Fa = 1.0;
Fb = (ab <= 0.0 || as >= ab) ? 0.0 : 1.0 - as / ab;
} else if (alphaMode == 4) {
//DISJOINT: ao = min(1, as + ab)
Fa = 1.0;
Fb = (ab <= 0.0) ? 0.0 : min(1.0, (1.0 - as) / ab);
} else {
//OVER
Fa = 1.0;
Fb = 1.0 - as;
}
outColor = vec4(as * Fa * mixed + ab * Fb * Cb, as * Fa + ab * Fb);
}
//UNORM target, also bounds legacy add.
fragColor = clamp(outColor, 0.0, 1.0);
}
""".trimIndent()
@@ -0,0 +1,261 @@
package org.umamo.render.glsl
/**
* The shared GLSL for Umamo's GPU deformation - the per-vertex morph + deformer cascade. Both the live
* renderer (`PuppetRenderer`, which projects the result to `gl_Position`) and the GPU-vs-CPU
* transform-feedback test (which captures the world position) prepend their own `#version` + in/out
* declarations and `main`, then call [deformWorld]. Sharing this snippet means the test exercises the
* exact deform math the renderer ships, not a hand-kept copy.
*
* The uniforms it declares are filled per pose from the backend-neutral `PoseDeformInputs`:
* - [deltaTex] - RG = a keyform cell's per-vertex delta; texel (col = cell linear index, row = vertex id).
* - cornerCount / cornerCell[] / cornerWeight[] - the active multilinear corners + weights.
* - parentType / rot[] / cpTex / warp* - the baked parent-deformer transform (0 direct, 1 rotation, 2 warp).
*/
internal const val DEFORM_GLSL =
"""
uniform sampler2D deltaTex;
uniform int cornerCount;
uniform int cornerCell[$MAX_CORNERS];
uniform float cornerWeight[$MAX_CORNERS];
uniform int blendCount;
uniform int blendCell[$MAX_BLEND_CORNERS];
uniform float blendWeight[$MAX_BLEND_CORNERS];
uniform int parentType;
uniform float rot[6];
uniform sampler2D cpTex;
uniform int warpCols;
uniform int warpRows;
uniform int warpBilinear;
vec2 cpAt(int index) {
int pointsPerRow = warpCols + 1;
return texelFetch(cpTex, ivec2(index % pointsPerRow, index / pointsPerRow), 0).rg;
}
vec2 warpExtrap(vec2 uv) {
int pointsPerRow = warpCols + 1;
int lastRowBase = warpRows * pointsPerRow;
vec2 topLeft = cpAt(0);
vec2 topRight = cpAt(warpCols);
vec2 botLeft = cpAt(lastRowBase);
vec2 botRight = cpAt(warpCols + lastRowBase);
float gridU = float(warpCols) * uv.x;
float gridV = float(warpRows) * uv.y;
vec2 deltaU = ((botRight - topLeft) + (topRight - botLeft)) * 0.5;
vec2 deltaV = ((botRight - topLeft) - (topRight - botLeft)) * 0.5;
vec2 origin = (topLeft + topRight + botLeft + botRight) * 0.25 - (botRight - topLeft) * 0.5;
if (uv.x <= -2.0 || uv.x >= 3.0 || uv.y <= -2.0 || uv.y >= 3.0) {
return origin + deltaU * uv.x + deltaV * uv.y;
}
float blendU = 0.0;
float blendV = 0.0;
vec2 corner0 = vec2(0.0);
vec2 corner1 = vec2(0.0);
vec2 corner2 = vec2(0.0);
vec2 corner3 = vec2(0.0);
if (uv.x <= 0.0) {
blendU = (uv.x + 2.0) * 0.5;
corner3 = origin - 2.0 * deltaU;
if (uv.y <= 0.0) {
corner2 = topLeft;
blendV = (uv.y + 2.0) * 0.5;
corner1 = origin - 2.0 * deltaV;
corner0 = corner3 - 2.0 * deltaV;
} else if (uv.y < 1.0) {
int loIdx = int(gridV);
float edgeHi;
int hiIdx;
if (warpRows == loIdx) {
loIdx = warpRows - 1;
hiIdx = warpRows;
edgeHi = float(warpRows);
} else {
hiIdx = loIdx + 1;
edgeHi = float(loIdx + 1);
}
blendV = gridV - float(loIdx);
float edgeLo = float(loIdx) / float(warpRows);
corner1 = cpAt(loIdx * pointsPerRow);
corner2 = cpAt(hiIdx * pointsPerRow);
corner0 = edgeLo * deltaV + corner3;
corner3 = (edgeHi / float(warpRows)) * deltaV + corner3;
} else {
corner1 = botLeft;
blendV = (uv.y - 1.0) * 0.5;
corner0 = corner3 + deltaV;
corner3 = 3.0 * deltaV + corner3;
corner2 = 3.0 * deltaV + origin;
}
} else if (uv.x < 1.0) {
if (uv.y <= 0.0) {
int loIdx = int(gridU);
vec2 edge;
float edgeHi;
if (warpCols == loIdx) {
loIdx = warpCols - 1;
edge = topRight;
edgeHi = float(warpCols);
} else {
edge = cpAt(loIdx + 1);
edgeHi = float(loIdx + 1);
}
blendV = (uv.y + 2.0) * 0.5;
blendU = gridU - float(loIdx);
float edgeLo = float(loIdx) / float(warpCols);
corner3 = cpAt(loIdx);
corner2 = edge;
corner0 = (edgeLo * deltaU + origin) - 2.0 * deltaV;
corner1 = ((edgeHi / float(warpCols)) * deltaU + origin) - 2.0 * deltaV;
} else if (uv.y >= 1.0) {
int loIdx = int(gridU);
float edgeHi;
int hiIdx;
if (warpCols == loIdx) {
loIdx = warpCols - 1;
hiIdx = warpCols;
edgeHi = float(warpCols);
} else {
hiIdx = loIdx + 1;
edgeHi = float(loIdx + 1);
}
blendV = (uv.y - 1.0) * 0.5;
blendU = gridU - float(loIdx);
float edgeLo = float(loIdx) / float(warpCols);
corner0 = cpAt(loIdx + lastRowBase);
corner1 = cpAt(lastRowBase + hiIdx);
corner2 = (edgeHi / float(warpCols)) * deltaU + origin + 3.0 * deltaV;
corner3 = edgeLo * deltaU + origin + 3.0 * deltaV;
} else {
return origin + deltaU * uv.x + deltaV * uv.y;
}
} else {
blendU = (uv.x - 1.0) * 0.5;
corner2 = 3.0 * deltaU + origin;
if (uv.y <= 0.0) {
corner3 = topRight;
blendV = (uv.y + 2.0) * 0.5;
corner0 = (origin + deltaU) - 2.0 * deltaV;
corner1 = corner2 - 2.0 * deltaV;
} else if (uv.y < 1.0) {
int loIdx = int(gridV);
float edgeHi;
int hiIdx;
if (warpRows == loIdx) {
loIdx = warpRows - 1;
hiIdx = warpRows;
edgeHi = float(warpRows);
} else {
hiIdx = loIdx + 1;
edgeHi = float(loIdx + 1);
}
blendV = gridV - float(loIdx);
corner0 = cpAt(loIdx * pointsPerRow + warpCols);
corner3 = cpAt(hiIdx * pointsPerRow + warpCols);
float edgeLo = float(loIdx) / float(warpRows);
corner1 = edgeLo * deltaV + corner2;
corner2 = (edgeHi / float(warpRows)) * deltaV + corner2;
} else {
corner0 = botRight;
blendV = (uv.y - 1.0) * 0.5;
corner1 = corner2 + deltaV;
corner3 = origin + deltaU + 3.0 * deltaV;
corner2 = 3.0 * deltaV + corner2;
}
}
if (blendU + blendV <= 1.0) {
return (corner1 - corner0) * blendU + corner0 + (corner3 - corner0) * blendV;
}
return (corner3 - corner2) * (1.0 - blendU) + corner2 + (corner1 - corner2) * (1.0 - blendV);
}
// Warp lattice map of normalized (u,v): in-grid bilinear/triangle blend of the 4 surrounding control
// points, else warpExtrap's full edge-blend extrapolation outside the lattice (ported from the CPU).
vec2 warpDeform(vec2 uv) {
int pointsPerRow = warpCols + 1;
if (uv.x >= 0.0 && uv.y >= 0.0 && uv.x < 1.0 && uv.y < 1.0) {
float gridU = float(warpCols) * uv.x;
float gridV = float(warpRows) * uv.y;
int cellU = int(gridU);
int cellV = int(gridV);
float fu = gridU - float(cellU);
float fv = gridV - float(cellV);
int cell = cellV * pointsPerRow + cellU;
vec2 p00 = cpAt(cell);
vec2 p10 = cpAt(cell + 1);
vec2 p01 = cpAt(cell + pointsPerRow);
vec2 p11 = cpAt(cell + pointsPerRow + 1);
if (warpBilinear == 0) {
if (fu + fv <= 1.0) {
return p10 * fu + p00 * (1.0 - fu - fv) + p01 * fv;
}
float w = (fu - 1.0) + fv;
return p01 * (1.0 - fu) + p11 * w + p10 * (1.0 - fv);
}
float ifv = 1.0 - fv;
return p10 * (fu * ifv) + p00 * ((1.0 - fu) * ifv) + p01 * ((1.0 - fu) * fv) + p11 * (fu * fv);
}
return warpExtrap(uv);
}
// Full per-vertex deform: blend base + Σ wᵢ·Δᵢ (active cells fetched from deltaTex by gl_VertexID),
// push through the parent transform (rotation affine / warp lattice / none), then negate Y. Glue is
// not applied here (a cross-mesh post-pass) - matches the CPU deform before its glue weld.
vec2 deformWorld(vec2 base) {
vec2 local = base;
for (int corner = 0; corner < cornerCount && corner < $MAX_CORNERS; corner++) {
vec2 delta = texelFetch(deltaTex, ivec2(cornerCell[corner], gl_VertexID), 0).rg;
local += cornerWeight[corner] * delta;
}
// Blend shapes: additive delta columns appended after the grid cells in deltaTex, weighted
// per pose (zero-blend models keep blendCount == 0 and skip the loop entirely).
for (int blendCorner = 0; blendCorner < blendCount && blendCorner < $MAX_BLEND_CORNERS; blendCorner++) {
vec2 blendDelta = texelFetch(deltaTex, ivec2(blendCell[blendCorner], gl_VertexID), 0).rg;
local += blendWeight[blendCorner] * blendDelta;
}
vec2 world;
if (parentType == 1) {
world = vec2(rot[3] * local.y + rot[0] * local.x + rot[4],
local.y * rot[1] + local.x * rot[2] + rot[5]);
} else if (parentType == 2) {
world = warpDeform(local);
} else {
world = local;
}
world.y = -world.y;
return world;
}
"""
/**
* The transform-feedback deform shader: runs [DEFORM_GLSL]'s `deformWorld` and captures the result as
* `outWorld` (no projection).
*
* Used by the renderer's glue pass 1 to write every glue mesh's deformed world positions into the shared
* position buffer, and by the GPU-vs-CPU validation test - which is the point: the test pins the exact
* deform body that ships, not a copy of it. Its varying `outWorld` must be registered via
* `glTransformFeedbackVaryings` before linking.
*
* Transform feedback is core in GL 3.3 AND GLES 3.0, so both dialects can run this as-is.
*
* @param GlslDialect dialect The target flavor.
* @return String The ready-to-compile source.
*/
internal fun tfDeformVertexShader(dialect: GlslDialect): String =
glslHeader(dialect) +
"layout(location = 0) in vec2 inBase;\n" +
"out vec2 outWorld;\n" +
DEFORM_GLSL.trimIndent() + "\n" +
"void main() {\n" +
" outWorld = deformWorld(inBase);\n" +
" gl_Position = vec4(0.0, 0.0, 0.0, 1.0);\n" +
"}\n"
/**
* The do-nothing fragment stage the transform-feedback program links against - it captures vertices and
* rasterizes nothing, but a program still needs a fragment shader to link.
*
* @param GlslDialect dialect The target flavor.
* @return String The ready-to-compile source.
*/
internal fun tfDiscardFragmentShader(dialect: GlslDialect): String = glslHeader(dialect) + "void main() {}\n"
@@ -0,0 +1,35 @@
package org.umamo.render.glsl
/**
* A GLSL flavor one of the GL-family backends compiles.
*
* The sources in this package are shared by the desktop GL 3.3 core backend and the Android GLES 3.0
* one, which want the same bodies behind different preambles. A Metal backend shares NOTHING here - MSL
* is a different language, supplied by that backend - so this enum is deliberately GL-family only rather
* than pretending to be a backend-neutral shader abstraction.
*
* GL 系(デスクトップ GL 3.3 / Android GLES 3.0)のシェーダ方言。Metal は MSL を別途持つ。
*/
internal enum class GlslDialect {
/** Desktop OpenGL 3.3 core profile. */
Core330,
/** OpenGL ES 3.0 - the Android baseline (3.0 is the floor because VAOs and gl_VertexID need it). */
Es300,
}
/**
* The `#version` preamble for [dialect], including the precision qualifiers ES requires.
*
* ES has no default precision for floats or ints in a fragment shader, so omitting these is a compile
* error there and a silent no-op on desktop - which is exactly the sort of divergence that made keeping
* two hand-copied shader sets untenable.
*
* @param GlslDialect dialect The target flavor.
* @return String The preamble, newline-terminated.
*/
internal fun glslHeader(dialect: GlslDialect): String =
when (dialect) {
GlslDialect.Core330 -> "#version 330 core\n"
GlslDialect.Es300 -> "#version 300 es\nprecision highp float;\nprecision highp int;\n"
}
@@ -0,0 +1,195 @@
package org.umamo.render.glsl
// The puppet render programs' GLSL, shared by the GL-family backends.
//
// Each builder returns a READY-TO-COMPILE source: the preamble is already applied and there is no
// `trimIndent()` left for a caller to remember. That is deliberate - the sources these replaced were
// trimmed inconsistently (inside the backdrop's `link`, at the call site for the fragment shader, and
// not at all for the concatenated vertex shaders), which is a trap with no upside.
//
// Metal shares none of this; see GlslDialect.
/**
* The live-render vertex shader: deforms via [DEFORM_GLSL]'s `deformWorld`, then projects.
*
* The deform body is shared with the glue pass-1 capture shader and the GPU-vs-CPU validation test, so
* all three exercise identical math rather than three hand-kept copies.
*
* @param GlslDialect dialect The target flavor.
* @return String The ready-to-compile source.
*/
internal fun puppetVertexShader(dialect: GlslDialect): String =
glslHeader(dialect) +
"layout(location = 0) in vec2 inBase;\n" + // rest-pose position (parent-deformer-local space)
"layout(location = 1) in vec2 inUv;\n" + // atlas texture coordinate (CMO3 [0,1])
"uniform vec4 worldToNdc;\n" + // (scaleX, scaleY, offsetX, offsetY) - the camera's world→NDC affine
"out vec2 vUv;\n" +
DEFORM_GLSL.trimIndent() + "\n" +
"void main() {\n" +
" vUv = inUv;\n" +
" vec2 world = deformWorld(inBase);\n" +
" gl_Position = vec4(world.x * worldToNdc.x + worldToNdc.z, world.y * worldToNdc.y + worldToNdc.w, 0.0, 1.0);\n" +
"}\n"
/**
* The glue pass-2 vertex shader: welds against pass-1's shared positions, then projects.
*
* Positions are NOT deformed here - pass 1 already wrote them to the shared position buffer (world
* space, post-Y-flip). Each vertex reads its own deformed position and, when it is a glued seam vertex,
* its partner's, and applies `own + (partner − own)·w·intensity` on the GPU, matching the CPU
* `applyGluesResolved`. Non-glued vertices pass through unchanged.
*
* @param GlslDialect dialect The target flavor.
* @return String The ready-to-compile source.
* @warning The [GlslDialect.Es300] output is NOT compilable as-is: `samplerBuffer` is GLES 3.2, and the
* Android baseline is 3.0. Making it portable means repacking the shared position buffer as a regular
* 2D texture indexed `(i % width, i / width)` - see TODO.md § Android GLES renderer backend option (b).
* The parameter is accepted here so the seam exists, not because ES works today.
*/
internal fun glueVertexShader(dialect: GlslDialect): String =
glslHeader(dialect) +
"layout(location = 1) in vec2 inUv;\n" +
"layout(location = 2) in int inPartnerIndex;\n" + // partner vertex's global index, or own when not glued
"layout(location = 3) in int inGlueIndex;\n" + // which glue (for its per-pose intensity), or -1
"layout(location = 4) in float inWeldWeight;\n" + // this vertex's weld weight (0 when not glued)
"uniform vec4 worldToNdc;\n" +
"uniform samplerBuffer positionBuffer;\n" + // RG = pass-1 deformed world positions, by global index
"uniform int baseOffset;\n" + // this mesh's base index in positionBuffer
"uniform float glueIntensity[$MAX_GLUES];\n" +
"out vec2 vUv;\n" +
"void main() {\n" +
" vUv = inUv;\n" +
" vec2 own = texelFetch(positionBuffer, baseOffset + gl_VertexID).rg;\n" +
" vec2 world = own;\n" +
// Skip the partner read when the weld is a no-op: a zero per-pose intensity also flags an unposed
// partner (set CPU-side), whose position-buffer region is uninitialised - so it is never read.
" if (inGlueIndex >= 0 && inWeldWeight != 0.0 && glueIntensity[inGlueIndex] != 0.0) {\n" +
" vec2 partner = texelFetch(positionBuffer, inPartnerIndex).rg;\n" +
" vec2 welded = own + (partner - own) * (inWeldWeight * glueIntensity[inGlueIndex]); if (welded.x == welded.x && welded.y == welded.y && distance(welded, own) < 100000.0) { world = welded; }\n" +
" }\n" +
" gl_Position = vec4(world.x * worldToNdc.x + worldToNdc.z, world.y * worldToNdc.y + worldToNdc.w, 0.0, 1.0);\n" +
"}\n"
/**
* The shared puppet fragment shader: samples the bound art texture through the stored-to-sampled uv
* affine (or a flat color), applies the clip mask, tints the selection highlight, and writes
* PREMULTIPLIED alpha (`rgb * alpha, alpha`) - which is why every blend mode's source factor is `GL_ONE`.
*
* A linear art texture is filtered in-shader, in premultiplied space: four `texelFetch` taps, each
* weighted by its own coverage, then converted back to straight color for the tint math. Art is stored
* straight, and the hardware filter averages straight colors, so an alpha edge takes on whatever color
* the neighboring transparent texels hold - black on every CMO3 layer image, and on any page composed
* from them - as a dark, texel-stepped fringe. Because the taps bypass the sampler, the shader applies
* the texture's wrap itself, told by the `atlasTransparentBorder` flag; a nearest texture reads one
* texel, where the two color spaces agree, so it keeps the hardware lookup. A port must keep this
* filter rather than trade it back for a plain `texture()` call.
*
* The mask is sampled by `gl_FragCoord.xy / screenTexSize` - screen space, with the divisor the mask
* texture's ALLOCATED size (equal to the viewport size only when the texture is exactly viewport-sized;
* side targets are grow-only, so it is usually the high-water capacity). The coverage pass renders at
* the same origin-anchored viewport, so fragment (x, y) reads coverage texel (x, y) exactly. That is
* self-consistent under either framebuffer origin convention (GL's bottom-left, Metal's top-left) and so
* needs no per-dialect flip; it only holds while the mask pass and this pass share a convention, which a
* port must keep true.
*
* @param GlslDialect dialect The target flavor.
* @return String The ready-to-compile source.
*/
internal fun puppetFragmentShader(dialect: GlslDialect): String =
glslHeader(dialect) +
"""
in vec2 vUv;
out vec4 fragColor;
uniform sampler2D atlas;
uniform int useTexture;
uniform vec4 drawColor;
uniform float opacity;
uniform int useMask;
uniform sampler2D maskTexture;
uniform vec2 screenTexSize;
uniform int invertMask;
uniform vec3 multiplyColor;
uniform vec3 screenColor;
uniform float highlight;
uniform vec3 highlightColor;
// The stored-to-sampled texture-coordinate affine, as two row vectors (m00 m01 m02 / m10 m11 m12).
// Rows rather than a mat3 because the value arrives row-major and a GLSL mat3 is column-major -
// passing rows keeps one convention end to end, and transliterates to MSL unchanged. Identity
// for a drawable sampling the atlas it was authored against.
uniform vec3 uvAffineRow0;
uniform vec3 uvAffineRow1;
// How the bound art texture was created: 1 when it filters linearly (0 nearest), and 1 when it
// wraps to a transparent border (0 to its edge texels).
uniform int atlasLinear;
uniform int atlasTransparentBorder;
// One art texel, premultiplied. A texel outside the image reads as the texture's wrap says.
vec4 premultipliedTexel(ivec2 texel, ivec2 size) {
if (atlasTransparentBorder == 1 && (any(lessThan(texel, ivec2(0))) || any(greaterThanEqual(texel, size)))) {
return vec4(0.0);
}
vec4 straight = texelFetch(atlas, clamp(texel, ivec2(0), size - ivec2(1)), 0);
return vec4(straight.rgb * straight.a, straight.a);
}
// The art at a texture coordinate, as straight color. Linear filtering blends the four surrounding
// texels premultiplied, so a transparent texel's color never reaches the edge it borders.
vec4 sampleArt(vec2 uv) {
if (atlasLinear == 0) {
return texture(atlas, uv);
}
ivec2 size = textureSize(atlas, 0);
vec2 corner = uv * vec2(size) - 0.5;
vec2 cornerFloor = floor(corner);
vec2 fraction = corner - cornerFloor;
ivec2 origin = ivec2(cornerFloor);
vec4 firstRow = mix(premultipliedTexel(origin, size), premultipliedTexel(origin + ivec2(1, 0), size), fraction.x);
vec4 secondRow = mix(premultipliedTexel(origin + ivec2(0, 1), size), premultipliedTexel(origin + ivec2(1, 1), size), fraction.x);
vec4 premultiplied = mix(firstRow, secondRow, fraction.y);
if (premultiplied.a <= 0.0) {
return vec4(0.0);
}
return vec4(min(premultiplied.rgb / premultiplied.a, vec3(1.0)), premultiplied.a);
}
void main() {
vec3 uvHomogeneous = vec3(vUv, 1.0);
vec2 sampleUv = vec2(dot(uvAffineRow0, uvHomogeneous), dot(uvAffineRow1, uvHomogeneous));
vec4 base = (useTexture == 1) ? sampleArt(sampleUv) : drawColor;
float alpha = base.a * opacity;
if (useMask == 1) {
float coverage = texture(maskTexture, gl_FragCoord.xy / screenTexSize).a;
alpha *= (invertMask == 1) ? (1.0 - coverage) : coverage;
}
vec3 tinted = base.rgb * multiplyColor;
tinted = tinted + screenColor - tinted * screenColor;
vec3 rgb = mix(tinted, highlightColor, highlight);
fragColor = vec4(rgb * alpha, alpha);
}
""".trimIndent()
/**
* The UV editor's underlay vertex shader, for an atlas page or a source-layer image.
*
* Emits the underlay rectangle's four corners from `gl_VertexID` (no vertex buffer, only an empty VAO),
* directly in Y-up display / texel space - world X in [0, W], Y in [0, H] - with NO Cubism Y negation
* (unlike `deformWorld`: the image is placed straight into the already-Y-up display space). The UVs carry
* the V-flip so the image's V=0 (its top texel row) lands at the top of the Y-up quad - corner (0, H) ->
* uv (0, 0) - matching UvDisplayMapping's `displayY = (1-v)*H`. Projects through the same worldToNdc
* affine as the puppet.
*
* That V-flip is a CONTENT convention (Y-up display vs top-first image rows), not a backend one, so it is
* identical in MSL - a Metal port must keep it, not "correct" it for Metal's top-left texture origin.
*
* @param GlslDialect dialect The target flavor.
* @return String The ready-to-compile source.
*/
internal fun atlasPageVertexShader(dialect: GlslDialect): String =
glslHeader(dialect) +
"uniform vec4 worldToNdc;\n" + // (scaleX, scaleY, offsetX, offsetY) - the camera's world→NDC affine
"uniform vec2 pageSize;\n" + // the underlay image's size in texels (W, H)
"out vec2 vUv;\n" +
"void main() {\n" +
" float cornerX = float(gl_VertexID & 1);\n" + // 0,1,0,1 across the triangle strip
" float cornerY = float((gl_VertexID >> 1) & 1);\n" + // 0,0,1,1
" vec2 world = vec2(cornerX * pageSize.x, cornerY * pageSize.y);\n" +
" vUv = vec2(cornerX, 1.0 - cornerY);\n" + // V-flip: display top (Y=H) samples the image's top row (v=0)
" gl_Position = vec4(world.x * worldToNdc.x + worldToNdc.z, world.y * worldToNdc.y + worldToNdc.w, 0.0, 1.0);\n" +
"}\n"
@@ -0,0 +1,58 @@
package org.umamo.render.glsl
// The limits and binding points the shader sources and the backends must agree on.
//
// These are a CONTRACT, not tuning knobs: each is interpolated into the GLSL below and read by the
// backend that fills the matching uniform, so the two cannot be changed independently. They live here,
// beside the sources that interpolate them, precisely so that stays true - [MAX_CORNERS] previously sat
// in the desktop renderer while the GLSL hardcoded a bare `16` in three places, which meant changing the
// constant silently disagreed with the shader.
/**
* The most keyform-grid corners a single mesh's morph can blend at once.
*
* A hard ceiling, not a guess: it sizes the `cornerCell` / `cornerWeight` uniform arrays, so a mesh with
* more active corners has the surplus dropped rather than blended. 16 corners is a 4-dimensional
* keyform grid (2^4).
*/
internal const val MAX_CORNERS = 16
/**
* The most blend-shape delta columns a single mesh can have active at once.
*
* Sizes the `blendCell` / `blendWeight` uniform arrays - the additive blend-shape pass's analogue
* of [MAX_CORNERS], kept SEPARATE so zero-blend models keep exactly the pre-blend uniform traffic.
* Corpus maximum is 18 active forms (Model C: 9 bindings x 2 bracketing keys); 32 gives headroom at a
* worst-case cost of 64 uniform components against GL 3.3 / GLES 3.0's guaranteed 1024. Surplus
* contributions are dropped deterministically, with the same cap applied CPU-side.
*/
internal const val MAX_BLEND_CORNERS = 32
/**
* The most glue affecters one model can weld on the GPU.
*
* Sizes the `glueIntensity` uniform array. A model's glue #65 and beyond render UNWELDED rather than
* failing - the renderer drops them when resolving the pose. A shader contract, so raising it means
* raising the array here and re-checking the uniform budget, not just editing a number.
*/
internal const val MAX_GLUES = 64
/**
* How strongly a selected drawable tints toward the selection accent (0 = untinted, 1 = fully the accent).
* A subtle wash, so the art stays readable under the highlight.
*/
internal const val SELECTION_TINT_STRENGTH = 0.35f
// Texture units, shared across every program so the per-mesh deform uniforms can be set the same way
// regardless of which program is bound. atlas/mask are fragment-stage; delta/cp/position are
// vertex-stage (texture fetch).
internal const val UNIT_ATLAS = 0
internal const val UNIT_MASK = 1
internal const val UNIT_DELTA = 2
internal const val UNIT_CP = 3
internal const val UNIT_POSITION = 4
// The composite pass's two extra fragment samplers: the rendered layer (the isolated subtree's
// buffer) and the destination snapshot it blends against.
internal const val UNIT_LAYER = 5
internal const val UNIT_DEST = 6
@@ -0,0 +1,329 @@
package org.umamo.render.pick
import org.umamo.runtime.model.DrawableId
import kotlin.math.PI
import kotlin.math.abs
import kotlin.math.cos
import kotlin.math.sin
/** Minimum atlas-texel alpha (0..1) for a click to count as a hit — rejects the transparent triangle
* overhang that art meshes carry past the visible art edge, while keeping faint-but-real art (~10/255). */
const val PICK_ALPHA_THRESHOLD = 0.04f
// Centrality (how deep inside the opaque region a hit is) ray-march tuning, in texture-space texels.
private const val CENTRALITY_RAY_COUNT = 16
private const val CENTRALITY_MAX_RADIUS_TEXELS = 64f
private const val CENTRALITY_STEP_TEXELS = 2f
/**
* One opaque candidate under the cursor: the drawable, its front-rank (higher = drawn more in front),
* and its centrality (0..1, higher = the click is deeper inside the opaque art). Used to build the
* overlap-picker popup.
*
* カーソル下の不透明候補。前面ランクと中心度を持つ。
*/
data class PickCandidate(val id: DrawableId, val frontRank: Float, val centrality: Float)
/**
* Reports whether a point lies inside (or on an edge of) a triangle, using the sign of the three edge
* cross products. Works for either winding order; a point exactly on an edge counts as inside. A
* degenerate (zero-area) triangle accepts only points lying on its collapsed span.
*
* 点が三角形の内部(辺上を含む)にあるかを、3辺の外積の符号で判定する。巻き方向に依存しない。
*
* @param Float pointX The test point X.
* @param Float pointY The test point Y.
* @param Float firstX First vertex X.
* @param Float firstY First vertex Y.
* @param Float secondX Second vertex X.
* @param Float secondY Second vertex Y.
* @param Float thirdX Third vertex X.
* @param Float thirdY Third vertex Y.
* @return Boolean True when the point is inside or on the triangle.
*/
fun pointInTriangle(
pointX: Float,
pointY: Float,
firstX: Float,
firstY: Float,
secondX: Float,
secondY: Float,
thirdX: Float,
thirdY: Float,
): Boolean {
val sideAb = edgeSide(pointX, pointY, firstX, firstY, secondX, secondY)
val sideBc = edgeSide(pointX, pointY, secondX, secondY, thirdX, thirdY)
val sideCa = edgeSide(pointX, pointY, thirdX, thirdY, firstX, firstY)
val hasNegative = sideAb < 0f || sideBc < 0f || sideCa < 0f
val hasPositive = sideAb > 0f || sideBc > 0f || sideCa > 0f
// Inside when the point is not strictly on both sides of the edges (zero counts as on-edge).
return !(hasNegative && hasPositive)
}
/**
* The signed area term for the point relative to the directed edge (start to end): positive on one
* side, negative on the other, zero on the line. The sign, not the magnitude, is what
* [pointInTriangle] consumes.
*
* 点と有向辺の符号付き面積項。
*
* @param Float pointX The test point X.
* @param Float pointY The test point Y.
* @param Float startX Edge start X.
* @param Float startY Edge start Y.
* @param Float endX Edge end X.
* @param Float endY Edge end Y.
* @return Float The signed area term.
*/
private fun edgeSide(
pointX: Float,
pointY: Float,
startX: Float,
startY: Float,
endX: Float,
endY: Float,
): Float = (pointX - endX) * (startY - endY) - (startX - endX) * (pointY - endY)
/**
* The barycentric weights (w0, w1, w2) of a point relative to a triangle, used to interpolate
* per-vertex attributes (the UV) at a hit point. Weights sum to 1; a degenerate (zero-area) triangle
* returns equal thirds rather than dividing by zero.
*
* 三角形に対する点の重心座標。頂点属性(UV)の補間に使う。退化三角形は 1/3 ずつを返す。
*
* @param Float pointX The point X.
* @param Float pointY The point Y.
* @param Float firstX First vertex X.
* @param Float firstY First vertex Y.
* @param Float secondX Second vertex X.
* @param Float secondY Second vertex Y.
* @param Float thirdX Third vertex X.
* @param Float thirdY Third vertex Y.
* @return FloatArray The three weights (w0, w1, w2).
*/
fun barycentricWeights(
pointX: Float,
pointY: Float,
firstX: Float,
firstY: Float,
secondX: Float,
secondY: Float,
thirdX: Float,
thirdY: Float,
): FloatArray {
val denominator = (secondY - thirdY) * (firstX - thirdX) + (thirdX - secondX) * (firstY - thirdY)
if (abs(denominator) < 1e-7f) {
return floatArrayOf(1f / 3f, 1f / 3f, 1f / 3f)
}
val weightFirst = ((secondY - thirdY) * (pointX - thirdX) + (thirdX - secondX) * (pointY - thirdY)) / denominator
val weightSecond = ((thirdY - firstY) * (pointX - thirdX) + (firstX - thirdX) * (pointY - thirdY)) / denominator
val weightThird = 1f - weightFirst - weightSecond
return floatArrayOf(weightFirst, weightSecond, weightThird)
}
/**
* Finds the FRONT-MOST drawable whose deformed mesh contains the point AND whose texel there is opaque,
* or null on a miss. Candidates are the drawables present in [worldPositions] (the evaluator's visible
* set) that also have triangle [indices], [meshUvs], and a [frontRank] (so a drawable not actually drawn
* this frame is skipped). For each, the first containing triangle's UV is barycentric-interpolated and
* [sampleAlpha]d; a texel below [alphaThreshold] is rejected (the transparent overhang). Among the
* opaque hits, the highest [frontRank] wins — the renderer's resolved paint order, which is correct
* where the raw draw-order scalar (ignoring the group hierarchy) is not.
*
* 変形メッシュが点を含み、かつその位置のテクセルが不透明な最前面のドロウアブルを返す。前面ランクは
* レンダラの解決済み描画順に基づく(生のドローオーダー値ではない)。
*
* @param Float worldX The point X in post-deform world space.
* @param Float worldZ The point Z (up) in post-deform world space.
* @param Map<DrawableId, FloatArray> worldPositions Interleaved (x,y) deformed vertices per drawable.
* @param Map<DrawableId, IntArray> indices Triangle index triples per drawable.
* @param Map<DrawableId, FloatArray> meshUvs Interleaved (u,v) per vertex per drawable.
* @param Map<DrawableId, Float> frontRank Front rank per drawn drawable (higher = more front).
* @param Function sampleAlpha (id, u, v) -> texel alpha 0..1 (untextured = 1).
* @param Float alphaThreshold Minimum alpha to count as a hit.
* @return DrawableId The front-most opaque hit, or null on a miss.
*/
fun pickDrawable(
worldX: Float,
worldZ: Float,
worldPositions: Map<DrawableId, FloatArray>,
indices: Map<DrawableId, IntArray>,
meshUvs: Map<DrawableId, FloatArray>,
frontRank: Map<DrawableId, Float>,
sampleAlpha: (DrawableId, Float, Float) -> Float,
alphaThreshold: Float = PICK_ALPHA_THRESHOLD,
): DrawableId? {
var bestId: DrawableId? = null
var bestRank = Float.NEGATIVE_INFINITY
for ((drawableId, positions) in worldPositions) {
val triangleIndices = indices[drawableId] ?: continue
val uvs = meshUvs[drawableId] ?: continue
val rank = frontRank[drawableId] ?: continue
val uv = hitUv(worldX, worldZ, positions, triangleIndices, uvs) ?: continue
if (sampleAlpha(drawableId, uv[0], uv[1]) < alphaThreshold) {
continue
}
if (bestId == null || rank > bestRank) {
bestId = drawableId
bestRank = rank
}
}
return bestId
}
/**
* All opaque candidates under the point, FRONT-TO-BACK (front first), each with its centrality. Uses the
* same hit + alpha gate as [pickDrawable]; built for the overlap-picker popup. Centrality (how deep the
* hit is inside the opaque art) is computed per survivor from its atlas size via [atlasSizeOf]; an
* untextured drawable (null size) scores full centrality.
*
* 点の下の不透明候補すべてを前面順に返す(各々の中心度付き)。重なり選択ポップアップ用。
*
* @param Float worldX The point X in post-deform world space.
* @param Float worldZ The point Z (up) in post-deform world space.
* @param Map<DrawableId, FloatArray> worldPositions Interleaved (x,y) deformed vertices per drawable.
* @param Map<DrawableId, IntArray> indices Triangle index triples per drawable.
* @param Map<DrawableId, FloatArray> meshUvs Interleaved (u,v) per vertex per drawable.
* @param Map<DrawableId, Float> frontRank Front rank per drawn drawable (higher = more front).
* @param Function atlasSizeOf (id) -> the drawable's atlas (width, height), or null if untextured.
* @param Function sampleAlpha (id, u, v) -> texel alpha 0..1 (untextured = 1).
* @param Float alphaThreshold Minimum alpha to count as a hit.
* @return List the opaque candidates, front-to-back.
*/
fun pickAllDrawables(
worldX: Float,
worldZ: Float,
worldPositions: Map<DrawableId, FloatArray>,
indices: Map<DrawableId, IntArray>,
meshUvs: Map<DrawableId, FloatArray>,
frontRank: Map<DrawableId, Float>,
atlasSizeOf: (DrawableId) -> Pair<Int, Int>?,
sampleAlpha: (DrawableId, Float, Float) -> Float,
alphaThreshold: Float = PICK_ALPHA_THRESHOLD,
): List<PickCandidate> {
val candidates = mutableListOf<PickCandidate>()
for ((drawableId, positions) in worldPositions) {
val triangleIndices = indices[drawableId] ?: continue
val uvs = meshUvs[drawableId] ?: continue
val rank = frontRank[drawableId] ?: continue
val uv = hitUv(worldX, worldZ, positions, triangleIndices, uvs) ?: continue
if (sampleAlpha(drawableId, uv[0], uv[1]) < alphaThreshold) {
continue
}
val atlasSize = atlasSizeOf(drawableId)
val centrality =
if (atlasSize == null) {
1f
} else {
centralityAt(drawableId, uv[0], uv[1], atlasSize.first, atlasSize.second, sampleAlpha, alphaThreshold)
}
candidates += PickCandidate(drawableId, rank, centrality)
}
candidates.sortByDescending { candidate -> candidate.frontRank }
return candidates
}
/**
* Approximate "depth inside the opaque region" at a UV hit, in 0..1. Casts [CENTRALITY_RAY_COUNT] rays
* outward in texture space (stepping [CENTRALITY_STEP_TEXELS]) up to [CENTRALITY_MAX_RADIUS_TEXELS],
* finds the nearest texel where alpha drops below [alphaThreshold], and returns that min distance
* normalised by the cap (1 = no transparent texel within the cap, i.e. deep inside). The middle of a
* large opaque region scores high; a hit near a transparent boundary scores low. Approximate
* (ray-sampled, not an exact distance transform), and it cannot tell apart adjacently-packed atlas art.
*
* UV ヒット位置が不透明領域のどれだけ奥かを近似する(0..1)。テクスチャ空間で放射状にレイを飛ばし、
* 最も近い透明テクセルまでの距離を上限で正規化する。
*
* @param DrawableId id The drawable being scored.
* @param Float u The hit U (full-atlas).
* @param Float v The hit V (full-atlas).
* @param Int atlasWidth The drawable's atlas page width in texels.
* @param Int atlasHeight The drawable's atlas page height in texels.
* @param Function sampleAlpha (id, u, v) -> texel alpha 0..1.
* @param Float alphaThreshold The transparent cutoff.
* @return Float The centrality, 0..1.
*/
fun centralityAt(
id: DrawableId,
u: Float,
v: Float,
atlasWidth: Int,
atlasHeight: Int,
sampleAlpha: (DrawableId, Float, Float) -> Float,
alphaThreshold: Float = PICK_ALPHA_THRESHOLD,
): Float {
if (atlasWidth <= 0 || atlasHeight <= 0) {
return 1f
}
var minRadius = CENTRALITY_MAX_RADIUS_TEXELS
for (rayIndex in 0 until CENTRALITY_RAY_COUNT) {
val angle = 2.0 * PI * rayIndex / CENTRALITY_RAY_COUNT
val directionX = cos(angle).toFloat()
val directionY = sin(angle).toFloat()
var radius = CENTRALITY_STEP_TEXELS
while (radius <= CENTRALITY_MAX_RADIUS_TEXELS) {
val sampleU = u + directionX * radius / atlasWidth
val sampleV = v + directionY * radius / atlasHeight
if (sampleAlpha(id, sampleU, sampleV) < alphaThreshold) {
if (radius < minRadius) {
minRadius = radius
}
break
}
radius += CENTRALITY_STEP_TEXELS
}
}
return (minRadius / CENTRALITY_MAX_RADIUS_TEXELS).coerceIn(0f, 1f)
}
/**
* The barycentric-interpolated (u, v) at the first triangle of a drawable's mesh that contains the point,
* or null when no triangle does. Index triples address vertices in the interleaved [positions] and [uvs]
* arrays (vertex n at index 2n, 2n+1). Shared by [pickDrawable] and [pickAllDrawables].
*
* 点を含む最初の三角形での補間 UV を返す(無ければ null)。
*
* @param Float worldX The point X.
* @param Float worldZ The point Z (up).
* @param FloatArray positions Interleaved (x,y) deformed vertices.
* @param IntArray triangleIndices Triangle index triples.
* @param FloatArray uvs Interleaved (u,v) per vertex.
* @return FloatArray (u, v) at the hit, or null.
*/
private fun hitUv(
worldX: Float,
worldZ: Float,
positions: FloatArray,
triangleIndices: IntArray,
uvs: FloatArray,
): FloatArray? {
var triangleStart = 0
while (triangleStart + 2 < triangleIndices.size) {
val firstVertex = triangleIndices[triangleStart] * 2
val secondVertex = triangleIndices[triangleStart + 1] * 2
val thirdVertex = triangleIndices[triangleStart + 2] * 2
if (
firstVertex + 1 < positions.size &&
secondVertex + 1 < positions.size &&
thirdVertex + 1 < positions.size &&
firstVertex + 1 < uvs.size &&
secondVertex + 1 < uvs.size &&
thirdVertex + 1 < uvs.size
) {
val ax = positions[firstVertex]
val ay = positions[firstVertex + 1]
val bx = positions[secondVertex]
val by = positions[secondVertex + 1]
val cx = positions[thirdVertex]
val cy = positions[thirdVertex + 1]
if (pointInTriangle(worldX, worldZ, ax, ay, bx, by, cx, cy)) {
val weights = barycentricWeights(worldX, worldZ, ax, ay, bx, by, cx, cy)
val hitU = weights[0] * uvs[firstVertex] + weights[1] * uvs[secondVertex] + weights[2] * uvs[thirdVertex]
val hitV = weights[0] * uvs[firstVertex + 1] + weights[1] * uvs[secondVertex + 1] + weights[2] * uvs[thirdVertex + 1]
return floatArrayOf(hitU, hitV)
}
}
triangleStart += 3
}
return null
}
@@ -0,0 +1,101 @@
package org.umamo.render.pick
import org.umamo.runtime.model.DrawableId
/*
* Region enclosure for object-mode box / circle select. Object selection is whole-drawable, so a region
* selects a drawable by its geometry CENTROID (the mean of its posed world vertices), Blender's object-mode
* rule: a drawable is selected when its centroid falls inside the box or circle. Centroid-inside is stable
* and predictable - a full-canvas layer whose centroid sits at the canvas center is not grabbed by a region
* that only grazes its edge, unlike an any-vertex-touching rule.
*
* These functions are pure and work in the same interleaved (x, y) world space as
* org.umamo.render.eval.DeformedGeometry.worldPositions, which is exactly what an overlay caches at
* gesture start and tests against each frame - so the selection math is unit-testable with no render or
* Compose context. Only drawables appear in worldPositions (deformers and parts have no viewport geometry),
* and hidden / mesh-less drawables are already absent, so the enclosure naturally covers only real drawables.
*
* オブジェクトモードのボックス / サークル選択の領域判定。描画メッシュの重心が領域内にあるとき選択する。
*/
/**
* The world-space centroid of each drawable: the mean of its interleaved (x, y) world vertices. A drawable
* with an empty array is skipped (it has no centroid to test).
*
* @param Map<DrawableId, FloatArray> worldPositions Interleaved world vertices per drawable.
* @return Map<DrawableId, FloatArray> A two-element [x, y] centroid per drawable.
*/
fun drawableCentroids(worldPositions: Map<DrawableId, FloatArray>): Map<DrawableId, FloatArray> {
val centroids = LinkedHashMap<DrawableId, FloatArray>(worldPositions.size)
for ((drawableId, positions) in worldPositions) {
var sumX = 0f
var sumY = 0f
var vertexCount = 0
var slotIndex = 0
while (slotIndex + 1 < positions.size) {
sumX += positions[slotIndex]
sumY += positions[slotIndex + 1]
vertexCount++
slotIndex += 2
}
if (vertexCount > 0) {
centroids[drawableId] = floatArrayOf(sumX / vertexCount, sumY / vertexCount)
}
}
return centroids
}
/**
* The drawables whose centroid lies inside the axis-aligned world rectangle (a box select). Boundaries are
* inclusive. The caller normalises the corners, so [minX] <= [maxX] and [minY] <= [maxY] is assumed.
*
* @param Map<DrawableId, FloatArray> centroids The per-drawable [x, y] centroids (see [drawableCentroids]).
* @param Float minX The rectangle's low x edge.
* @param Float minY The rectangle's low y edge.
* @param Float maxX The rectangle's high x edge.
* @param Float maxY The rectangle's high y edge.
* @return Set<DrawableId> The enclosed drawable ids.
*/
fun drawablesInBox(
centroids: Map<DrawableId, FloatArray>,
minX: Float,
minY: Float,
maxX: Float,
maxY: Float,
): Set<DrawableId> {
val enclosed = LinkedHashSet<DrawableId>()
for ((drawableId, centroid) in centroids) {
if (centroid[0] in minX..maxX && centroid[1] in minY..maxY) {
enclosed.add(drawableId)
}
}
return enclosed
}
/**
* The drawables whose centroid lies within [radius] of ([centerX], [centerY]) in world space (a circle
* select brush stamp). A point exactly on the circle counts as inside.
*
* @param Map<DrawableId, FloatArray> centroids The per-drawable [x, y] centroids (see [drawableCentroids]).
* @param Float centerX The brush center x in world space.
* @param Float centerY The brush center y in world space.
* @param Float radius The brush radius in world units.
* @return Set<DrawableId> The enclosed drawable ids.
*/
fun drawablesInCircle(
centroids: Map<DrawableId, FloatArray>,
centerX: Float,
centerY: Float,
radius: Float,
): Set<DrawableId> {
val radiusSquared = radius * radius
val enclosed = LinkedHashSet<DrawableId>()
for ((drawableId, centroid) in centroids) {
val offsetX = centroid[0] - centerX
val offsetY = centroid[1] - centerY
if (offsetX * offsetX + offsetY * offsetY <= radiusSquared) {
enclosed.add(drawableId)
}
}
return enclosed
}
@@ -0,0 +1,531 @@
package org.umamo.render.pick
import org.umamo.render.ViewportCamera
import kotlin.math.max
import kotlin.math.min
import kotlin.math.sqrt
/*
* Screen-space hit-testing and region enclosure over an interleaved (x, y) positions array, projected
* through a ViewportCamera - the geometry seam the Edit-mode gizmo overlays use for element picking,
* box select, and the circle brush, and that a UV editor can reuse verbatim by projecting through its
* own camera. Everything here is pure and Compose-free: points are plain floats, sizes are plain ints,
* and results are ORDINALS - vertex indices, edge ordinals into the caller's edge array, and triangle
* ordinals - so this module never depends on any UI element type.
*
* Edges come in as an interleaved endpoint array (two vertex indices per edge, the caller's edge order);
* the point-in-triangle test is shared with the world-space picker (pointInTriangle in Picker.kt),
* which is coordinate-space agnostic.
*
* 画面空間のヒットテストと範囲選択。カメラで投影する純粋な幾何で、UI 型に依存しない(結果は序数)。
* UV エディタも同じ関数を自分のカメラで再利用できる。
*/
/**
* Maps a world x to its screen pixel x through [camera].
*
* @param Float worldX The world-space x.
* @param ViewportCamera camera The projecting camera.
* @param Int viewportWidth The viewport width in pixels.
* @return Float The screen x in pixels.
*/
fun worldToScreenX(worldX: Float, camera: ViewportCamera, viewportWidth: Int): Float =
(worldX - camera.centerX) * camera.zoom + viewportWidth / 2f
/**
* Maps a world z to its screen pixel y through [camera]. The vertical axis flips: screen y grows
* downward, world z grows upward.
*
* @param Float worldZ The world-space z (up).
* @param ViewportCamera camera The projecting camera.
* @param Int viewportHeight The viewport height in pixels.
* @return Float The screen y in pixels.
*/
fun worldToScreenY(worldZ: Float, camera: ViewportCamera, viewportHeight: Int): Float =
(camera.centerY - worldZ) * camera.zoom + viewportHeight / 2f
/**
* Maps a screen pixel x back to world space - the exact inverse of [worldToScreenX].
*
* @param Float screenX The screen x in pixels.
* @param ViewportCamera camera The projecting camera.
* @param Int viewportWidth The viewport width in pixels.
* @return Float The world-space x.
*/
fun screenToWorldX(screenX: Float, camera: ViewportCamera, viewportWidth: Int): Float =
camera.centerX + (screenX - viewportWidth / 2f) / camera.zoom
/**
* Maps a screen pixel y back to world space - the exact inverse of [worldToScreenY].
*
* @param Float screenY The screen y in pixels.
* @param ViewportCamera camera The projecting camera.
* @param Int viewportHeight The viewport height in pixels.
* @return Float The world-space z (up).
*/
fun screenToWorldZ(screenY: Float, camera: ViewportCamera, viewportHeight: Int): Float =
camera.centerY - (screenY - viewportHeight / 2f) / camera.zoom
/**
* The unclamped parameter of [point] along the infinite line through [start]→[end] (0 at start, 1 at
* end). A degenerate segment returns 0.5 so callers that clamp into `(ε, 1−ε)` still land mid-edge.
*
* @return Float The projection parameter (may lie outside [0, 1]).
*/
fun parameterAlongSegment(
pointX: Float,
pointY: Float,
startX: Float,
startY: Float,
endX: Float,
endY: Float,
): Float {
val segmentX = endX - startX
val segmentY = endY - startY
val lengthSquared = segmentX * segmentX + segmentY * segmentY
if (lengthSquared <= 1e-6f) {
return 0.5f
}
return ((pointX - startX) * segmentX + (pointY - startY) * segmentY) / lengthSquared
}
/**
* The distance from a point to the segment start-end: the point is projected onto the segment's line
* with the projection parameter clamped into [0, 1], so endpoints measure correctly. Space-agnostic
* (the gizmos use it in screen pixels).
*
* @param Float pointX The point x.
* @param Float pointY The point y.
* @param Float startX The segment start x.
* @param Float startY The segment start y.
* @param Float endX The segment end x.
* @param Float endY The segment end y.
* @return Float The distance.
*/
fun distanceToSegment(pointX: Float, pointY: Float, startX: Float, startY: Float, endX: Float, endY: Float): Float {
val segmentX = endX - startX
val segmentY = endY - startY
val lengthSquared = segmentX * segmentX + segmentY * segmentY
// A degenerate (zero-length) segment measures as the distance to its single point.
if (lengthSquared <= 1e-6f) {
val deltaX = pointX - startX
val deltaY = pointY - startY
return sqrt(deltaX * deltaX + deltaY * deltaY)
}
val clamped = parameterAlongSegment(pointX, pointY, startX, startY, endX, endY).coerceIn(0f, 1f)
val nearestX = startX + segmentX * clamped
val nearestY = startY + segmentY * clamped
val deltaX = pointX - nearestX
val deltaY = pointY - nearestY
return sqrt(deltaX * deltaX + deltaY * deltaY)
}
/**
* The vertex index under the pointer within [hitRadiusPx], or null. Picks the nearest within the radius.
*
* @param FloatArray positions The interleaved (x, y) world positions.
* @param Float pointerX The pointer x in screen pixels.
* @param Float pointerY The pointer y in screen pixels.
* @param Float hitRadiusPx The pick radius in screen pixels.
* @param ViewportCamera camera The projecting camera.
* @param Int viewportWidth The viewport width in pixels.
* @param Int viewportHeight The viewport height in pixels.
* @return Int? The hit vertex index, or null.
*/
fun hitTestVertex(
positions: FloatArray,
pointerX: Float,
pointerY: Float,
hitRadiusPx: Float,
camera: ViewportCamera,
viewportWidth: Int,
viewportHeight: Int,
): Int? {
var best = -1
var bestDistance = hitRadiusPx
val vertexCount = positions.size / 2
for (vertexIndex in 0 until vertexCount) {
val screenX = worldToScreenX(positions[vertexIndex * 2], camera, viewportWidth)
val screenY = worldToScreenY(positions[vertexIndex * 2 + 1], camera, viewportHeight)
val deltaX = screenX - pointerX
val deltaY = screenY - pointerY
val distance = sqrt(deltaX * deltaX + deltaY * deltaY)
if (distance <= bestDistance) {
bestDistance = distance
best = vertexIndex
}
}
return if (best >= 0) best else null
}
/**
* The edge under the pointer within [hitRadiusPx], or null. Picks the nearest by point-to-segment
* distance in screen space, so a click between two close edges resolves to the closer one.
*
* @param FloatArray positions The interleaved (x, y) world positions.
* @param IntArray edgeEndpoints The edges as interleaved endpoint vertex indices (two per edge).
* @param Float pointerX The pointer x in screen pixels.
* @param Float pointerY The pointer y in screen pixels.
* @param Float hitRadiusPx The pick radius in screen pixels.
* @param ViewportCamera camera The projecting camera.
* @param Int viewportWidth The viewport width in pixels.
* @param Int viewportHeight The viewport height in pixels.
* @return Int? The hit edge's ordinal (its pair index within [edgeEndpoints]), or null.
*/
fun hitTestEdge(
positions: FloatArray,
edgeEndpoints: IntArray,
pointerX: Float,
pointerY: Float,
hitRadiusPx: Float,
camera: ViewportCamera,
viewportWidth: Int,
viewportHeight: Int,
): Int? {
var best = -1
var bestDistance = hitRadiusPx
val vertexCount = positions.size / 2
val edgeCount = edgeEndpoints.size / 2
for (edgeOrdinal in 0 until edgeCount) {
val endpointA = edgeEndpoints[edgeOrdinal * 2]
val endpointB = edgeEndpoints[edgeOrdinal * 2 + 1]
if (endpointA >= vertexCount || endpointB >= vertexCount) {
continue
}
val startX = worldToScreenX(positions[endpointA * 2], camera, viewportWidth)
val startY = worldToScreenY(positions[endpointA * 2 + 1], camera, viewportHeight)
val endX = worldToScreenX(positions[endpointB * 2], camera, viewportWidth)
val endY = worldToScreenY(positions[endpointB * 2 + 1], camera, viewportHeight)
val distance = distanceToSegment(pointerX, pointerY, startX, startY, endX, endY)
if (distance <= bestDistance) {
bestDistance = distance
best = edgeOrdinal
}
}
return if (best >= 0) best else null
}
/**
* The triangle under the pointer, or null. A point-in-triangle test on the projected positions; when a
* deformed mesh overlaps itself and several triangles contain the pointer, the one with the nearest
* centroid wins (a deterministic tie-break that favors the face whose click affordance is closest).
*
* @param FloatArray positions The interleaved (x, y) world positions.
* @param IntArray triangleIndices The mesh triangle vertex indices (three per triangle).
* @param Float pointerX The pointer x in screen pixels.
* @param Float pointerY The pointer y in screen pixels.
* @param ViewportCamera camera The projecting camera.
* @param Int viewportWidth The viewport width in pixels.
* @param Int viewportHeight The viewport height in pixels.
* @return Int? The hit triangle's ordinal, or null.
*/
fun hitTestFace(
positions: FloatArray,
triangleIndices: IntArray,
pointerX: Float,
pointerY: Float,
camera: ViewportCamera,
viewportWidth: Int,
viewportHeight: Int,
): Int? {
var best = -1
var bestCentroidDistance = Float.MAX_VALUE
val vertexCount = positions.size / 2
val triangleCount = triangleIndices.size / 3
for (triangleOrdinal in 0 until triangleCount) {
val cornerA = triangleIndices[triangleOrdinal * 3]
val cornerB = triangleIndices[triangleOrdinal * 3 + 1]
val cornerC = triangleIndices[triangleOrdinal * 3 + 2]
if (cornerA >= vertexCount || cornerB >= vertexCount || cornerC >= vertexCount) {
continue
}
val screenAx = worldToScreenX(positions[cornerA * 2], camera, viewportWidth)
val screenAy = worldToScreenY(positions[cornerA * 2 + 1], camera, viewportHeight)
val screenBx = worldToScreenX(positions[cornerB * 2], camera, viewportWidth)
val screenBy = worldToScreenY(positions[cornerB * 2 + 1], camera, viewportHeight)
val screenCx = worldToScreenX(positions[cornerC * 2], camera, viewportWidth)
val screenCy = worldToScreenY(positions[cornerC * 2 + 1], camera, viewportHeight)
if (!pointInTriangle(pointerX, pointerY, screenAx, screenAy, screenBx, screenBy, screenCx, screenCy)) {
continue
}
val centroidX = (screenAx + screenBx + screenCx) / 3f
val centroidY = (screenAy + screenBy + screenCy) / 3f
val deltaX = pointerX - centroidX
val deltaY = pointerY - centroidY
val centroidDistance = sqrt(deltaX * deltaX + deltaY * deltaY)
if (centroidDistance < bestCentroidDistance) {
bestCentroidDistance = centroidDistance
best = triangleOrdinal
}
}
return if (best >= 0) best else null
}
/**
* The set of vertices whose screen projection lies inside the rectangle spanned by the two corners
* (a rubber-band box select).
*
* @param FloatArray positions The interleaved (x, y) world positions.
* @param Float cornerAx One box corner's x in screen pixels.
* @param Float cornerAy One box corner's y in screen pixels.
* @param Float cornerBx The opposite corner's x.
* @param Float cornerBy The opposite corner's y.
* @param ViewportCamera camera The projecting camera.
* @param Int viewportWidth The viewport width in pixels.
* @param Int viewportHeight The viewport height in pixels.
* @return Set<Int> The enclosed vertex indices.
*/
fun verticesInBox(
positions: FloatArray,
cornerAx: Float,
cornerAy: Float,
cornerBx: Float,
cornerBy: Float,
camera: ViewportCamera,
viewportWidth: Int,
viewportHeight: Int,
): Set<Int> {
val minX = min(cornerAx, cornerBx)
val maxX = max(cornerAx, cornerBx)
val minY = min(cornerAy, cornerBy)
val maxY = max(cornerAy, cornerBy)
val result = HashSet<Int>()
val vertexCount = positions.size / 2
for (vertexIndex in 0 until vertexCount) {
val screenX = worldToScreenX(positions[vertexIndex * 2], camera, viewportWidth)
val screenY = worldToScreenY(positions[vertexIndex * 2 + 1], camera, viewportHeight)
if (screenX in minX..maxX && screenY in minY..maxY) {
result.add(vertexIndex)
}
}
return result
}
/**
* The set of edges fully enclosed by the box (both endpoints inside) - Blender's edge box-select rule.
*
* @param FloatArray positions The interleaved (x, y) world positions.
* @param IntArray edgeEndpoints The edges as interleaved endpoint vertex indices (two per edge).
* @param Float cornerAx One box corner's x in screen pixels.
* @param Float cornerAy One box corner's y in screen pixels.
* @param Float cornerBx The opposite corner's x.
* @param Float cornerBy The opposite corner's y.
* @param ViewportCamera camera The projecting camera.
* @param Int viewportWidth The viewport width in pixels.
* @param Int viewportHeight The viewport height in pixels.
* @return Set<Int> The enclosed edges' ordinals.
*/
fun edgesInBox(
positions: FloatArray,
edgeEndpoints: IntArray,
cornerAx: Float,
cornerAy: Float,
cornerBx: Float,
cornerBy: Float,
camera: ViewportCamera,
viewportWidth: Int,
viewportHeight: Int,
): Set<Int> {
val insideVertices = verticesInBox(positions, cornerAx, cornerAy, cornerBx, cornerBy, camera, viewportWidth, viewportHeight)
val result = HashSet<Int>()
val edgeCount = edgeEndpoints.size / 2
for (edgeOrdinal in 0 until edgeCount) {
if (edgeEndpoints[edgeOrdinal * 2] in insideVertices && edgeEndpoints[edgeOrdinal * 2 + 1] in insideVertices) {
result.add(edgeOrdinal)
}
}
return result
}
/**
* The set of triangles whose screen centroid lies inside the box - matching the centroid dot drawn as
* the face-mode click affordance, so the box selects exactly the visible dots it covers.
*
* @param FloatArray positions The interleaved (x, y) world positions.
* @param IntArray triangleIndices The mesh triangle vertex indices (three per triangle).
* @param Float cornerAx One box corner's x in screen pixels.
* @param Float cornerAy One box corner's y in screen pixels.
* @param Float cornerBx The opposite corner's x.
* @param Float cornerBy The opposite corner's y.
* @param ViewportCamera camera The projecting camera.
* @param Int viewportWidth The viewport width in pixels.
* @param Int viewportHeight The viewport height in pixels.
* @return Set<Int> The enclosed triangles' ordinals.
*/
fun facesInBox(
positions: FloatArray,
triangleIndices: IntArray,
cornerAx: Float,
cornerAy: Float,
cornerBx: Float,
cornerBy: Float,
camera: ViewportCamera,
viewportWidth: Int,
viewportHeight: Int,
): Set<Int> {
val minX = min(cornerAx, cornerBx)
val maxX = max(cornerAx, cornerBx)
val minY = min(cornerAy, cornerBy)
val maxY = max(cornerAy, cornerBy)
val result = HashSet<Int>()
val vertexCount = positions.size / 2
val triangleCount = triangleIndices.size / 3
for (triangleOrdinal in 0 until triangleCount) {
val cornerA = triangleIndices[triangleOrdinal * 3]
val cornerB = triangleIndices[triangleOrdinal * 3 + 1]
val cornerC = triangleIndices[triangleOrdinal * 3 + 2]
if (cornerA >= vertexCount || cornerB >= vertexCount || cornerC >= vertexCount) {
continue
}
val centroidX =
(
worldToScreenX(positions[cornerA * 2], camera, viewportWidth) +
worldToScreenX(positions[cornerB * 2], camera, viewportWidth) +
worldToScreenX(positions[cornerC * 2], camera, viewportWidth)
) / 3f
val centroidY =
(
worldToScreenY(positions[cornerA * 2 + 1], camera, viewportHeight) +
worldToScreenY(positions[cornerB * 2 + 1], camera, viewportHeight) +
worldToScreenY(positions[cornerC * 2 + 1], camera, viewportHeight)
) / 3f
if (centroidX in minX..maxX && centroidY in minY..maxY) {
result.add(triangleOrdinal)
}
}
return result
}
/**
* The set of vertices whose screen projection lies within [radiusPx] of the brush center - the
* Circle-select brush.
*
* @param FloatArray positions The interleaved (x, y) world positions.
* @param Float centerX The brush center x in screen pixels.
* @param Float centerY The brush center y in screen pixels.
* @param Float radiusPx The brush radius in screen pixels.
* @param ViewportCamera camera The projecting camera.
* @param Int viewportWidth The viewport width in pixels.
* @param Int viewportHeight The viewport height in pixels.
* @return Set<Int> The enclosed vertex indices.
*/
fun verticesInCircle(
positions: FloatArray,
centerX: Float,
centerY: Float,
radiusPx: Float,
camera: ViewportCamera,
viewportWidth: Int,
viewportHeight: Int,
): Set<Int> {
val result = HashSet<Int>()
val vertexCount = positions.size / 2
for (vertexIndex in 0 until vertexCount) {
val deltaX = worldToScreenX(positions[vertexIndex * 2], camera, viewportWidth) - centerX
val deltaY = worldToScreenY(positions[vertexIndex * 2 + 1], camera, viewportHeight) - centerY
if (sqrt(deltaX * deltaX + deltaY * deltaY) <= radiusPx) {
result.add(vertexIndex)
}
}
return result
}
/**
* The set of edges the brush touches: an edge is included when the brush center is within [radiusPx] of
* the edge segment in screen space (Blender's circle brush paints any edge the disc overlaps).
*
* @param FloatArray positions The interleaved (x, y) world positions.
* @param IntArray edgeEndpoints The edges as interleaved endpoint vertex indices (two per edge).
* @param Float centerX The brush center x in screen pixels.
* @param Float centerY The brush center y in screen pixels.
* @param Float radiusPx The brush radius in screen pixels.
* @param ViewportCamera camera The projecting camera.
* @param Int viewportWidth The viewport width in pixels.
* @param Int viewportHeight The viewport height in pixels.
* @return Set<Int> The touched edges' ordinals.
*/
fun edgesInCircle(
positions: FloatArray,
edgeEndpoints: IntArray,
centerX: Float,
centerY: Float,
radiusPx: Float,
camera: ViewportCamera,
viewportWidth: Int,
viewportHeight: Int,
): Set<Int> {
val vertexCount = positions.size / 2
val result = HashSet<Int>()
val edgeCount = edgeEndpoints.size / 2
for (edgeOrdinal in 0 until edgeCount) {
val endpointA = edgeEndpoints[edgeOrdinal * 2]
val endpointB = edgeEndpoints[edgeOrdinal * 2 + 1]
if (endpointA >= vertexCount || endpointB >= vertexCount) {
continue
}
val startX = worldToScreenX(positions[endpointA * 2], camera, viewportWidth)
val startY = worldToScreenY(positions[endpointA * 2 + 1], camera, viewportHeight)
val endX = worldToScreenX(positions[endpointB * 2], camera, viewportWidth)
val endY = worldToScreenY(positions[endpointB * 2 + 1], camera, viewportHeight)
if (distanceToSegment(centerX, centerY, startX, startY, endX, endY) <= radiusPx) {
result.add(edgeOrdinal)
}
}
return result
}
/**
* The set of triangles whose screen centroid lies within [radiusPx] of the brush center - matching the
* centroid dot the face-mode overlay draws, so the brush paints the dots it covers (consistent with box
* select).
*
* @param FloatArray positions The interleaved (x, y) world positions.
* @param IntArray triangleIndices The mesh triangle vertex indices (three per triangle).
* @param Float centerX The brush center x in screen pixels.
* @param Float centerY The brush center y in screen pixels.
* @param Float radiusPx The brush radius in screen pixels.
* @param ViewportCamera camera The projecting camera.
* @param Int viewportWidth The viewport width in pixels.
* @param Int viewportHeight The viewport height in pixels.
* @return Set<Int> The touched triangles' ordinals.
*/
fun facesInCircle(
positions: FloatArray,
triangleIndices: IntArray,
centerX: Float,
centerY: Float,
radiusPx: Float,
camera: ViewportCamera,
viewportWidth: Int,
viewportHeight: Int,
): Set<Int> {
val result = HashSet<Int>()
val vertexCount = positions.size / 2
val triangleCount = triangleIndices.size / 3
for (triangleOrdinal in 0 until triangleCount) {
val cornerA = triangleIndices[triangleOrdinal * 3]
val cornerB = triangleIndices[triangleOrdinal * 3 + 1]
val cornerC = triangleIndices[triangleOrdinal * 3 + 2]
if (cornerA >= vertexCount || cornerB >= vertexCount || cornerC >= vertexCount) {
continue
}
val centroidX =
(
worldToScreenX(positions[cornerA * 2], camera, viewportWidth) +
worldToScreenX(positions[cornerB * 2], camera, viewportWidth) +
worldToScreenX(positions[cornerC * 2], camera, viewportWidth)
) / 3f
val centroidY =
(
worldToScreenY(positions[cornerA * 2 + 1], camera, viewportHeight) +
worldToScreenY(positions[cornerB * 2 + 1], camera, viewportHeight) +
worldToScreenY(positions[cornerC * 2 + 1], camera, viewportHeight)
) / 3f
val deltaX = centroidX - centerX
val deltaY = centroidY - centerY
if (sqrt(deltaX * deltaX + deltaY * deltaY) <= radiusPx) {
result.add(triangleOrdinal)
}
}
return result
}
@@ -0,0 +1,325 @@
package org.umamo.render.puppet
import org.umamo.runtime.model.AlphaBlendMode
import org.umamo.runtime.model.BlendMode
import kotlin.math.max
import kotlin.math.min
import kotlin.math.sqrt
/*
* The layer-composite reference math - the single spec the composite fragment shader
* (glsl/CompositeShaders.kt) and the analytic GL tests both follow. Sources are the PUBLIC
* standard formulas only: W3C Compositing and Blending Level 1 for the separable and
* non-separable (Hue/Color) blend functions, Porter-Duff for Over/Atop and a DST-flavored Out
* (the source erases the destination and contributes no color), the X Render extension's
* conjoint/disjoint over variants, and KHR_blend_equation_advanced's p0 overlap weights for how
* much of the source takes the blended color. Cubism's own `_TSL`/`_R2` math is NOT derived
* from the official SDK - the standard-formula reading has been checked against the official
* editor's rendering of Model A's authored combinations (NORMAL / MULTIPLY_R2 composites; HSL_COLOR /
* ADD_R2 (Glow) / HARDLIGHT / MULTIPLY_R2 drawable blends; OVER / ATOP / OUT / DISJOINT alphas).
* OUT in particular was confirmed DST-flavored: the SRC-out reading rendered Model A's hologram
* cutouts as destination-erasing silhouettes instead of cutting the effect to the body shape.
* Combinations the corpus does not yet exercise with real art (the remaining `_TSL` variants,
* Conjoint) are unconfirmed against the editor.
*
* Everything operates on PREMULTIPLIED RGBA (the renderer's framebuffer convention). The fixed-function
* premultiplied path replicates the equations of GlFrameEncoder.applyBlend EXACTLY (pinned by a
* shader==fixed-function GL test) and is taken by legacy Normal under Over alpha, plus
* AdditivePremultiplied / MultiplyPremultiplied under ANY alpha mode - the "(Before 5.3)" Add and
* Multiply ignore the Alpha blend setting per the Cubism editor. Every other combination takes the
* generic unpremultiply -> blend -> Porter-Duff path.
*/
/**
* The composite shader's colorMode int for a blend mode - the MOC3 packed encoding's color half
* (editor-dropdown order, legacy first; MUST agree with BlendModeMapping.colorBlendOfPacked).
*
* @param BlendMode blendMode The color blend mode.
* @return Int The shader's colorMode uniform value (0-17).
*/
public fun packedColorModeOf(blendMode: BlendMode): Int =
when (blendMode) {
BlendMode.Normal -> 0
BlendMode.AdditivePremultiplied -> 1
BlendMode.MultiplyPremultiplied -> 2
BlendMode.Additive -> 3
BlendMode.AdditiveGlow -> 4
BlendMode.Darken -> 5
BlendMode.Multiply -> 6
BlendMode.ColorBurn -> 7
BlendMode.LinearBurn -> 8
BlendMode.Lighten -> 9
BlendMode.Screen -> 10
BlendMode.ColorDodge -> 11
BlendMode.Overlay -> 12
BlendMode.SoftLight -> 13
BlendMode.HardLight -> 14
BlendMode.LinearLight -> 15
BlendMode.Hue -> 16
BlendMode.Color -> 17
}
/**
* The composite shader's alphaMode int for an alpha blend mode - the MOC3 packed encoding's alpha
* half (dropdown order; MUST agree with BlendModeMapping.alphaBlendOfPacked).
*
* @param AlphaBlendMode alphaBlendMode The alpha blend mode.
* @return Int The shader's alphaMode uniform value (0-4).
*/
public fun packedAlphaModeOf(alphaBlendMode: AlphaBlendMode): Int =
when (alphaBlendMode) {
AlphaBlendMode.Over -> 0
AlphaBlendMode.Atop -> 1
AlphaBlendMode.Out -> 2
AlphaBlendMode.Conjoint -> 3
AlphaBlendMode.Disjoint -> 4
}
/**
* Composites one premultiplied source pixel over one premultiplied destination pixel.
*
* @param FloatArray srcPremul The layer pixel, premultiplied RGBA (after opacity, colors,
* and mask have been applied to it).
* @param FloatArray dstPremul The destination pixel, premultiplied RGBA.
* @param BlendMode blendMode The color blend mode.
* @param AlphaBlendMode alphaBlendMode The alpha blend mode.
* @return FloatArray The composited pixel, premultiplied RGBA, channels clamped to [0,1].
*/
public fun compositeReference(
srcPremul: FloatArray,
dstPremul: FloatArray,
blendMode: BlendMode,
alphaBlendMode: AlphaBlendMode,
): FloatArray {
val sourceAlpha = srcPremul[3]
val destinationAlpha = dstPremul[3]
// Fixed-function premultiplied path: legacy Normal under Over, and the "(Before 5.3)" Add/Multiply
// under ANY alpha (they ignore the Alpha blend setting). Everything else goes through the generic path.
if ((alphaBlendMode == AlphaBlendMode.Over && blendMode.isLegacy) || blendMode.ignoresAlphaBlend) {
val out =
when (blendMode) {
// (ONE, ONE_MINUS_SRC_ALPHA) on both color and alpha - premultiplied source-over.
BlendMode.Normal ->
floatArrayOf(
srcPremul[0] + dstPremul[0] * (1f - sourceAlpha),
srcPremul[1] + dstPremul[1] * (1f - sourceAlpha),
srcPremul[2] + dstPremul[2] * (1f - sourceAlpha),
sourceAlpha + destinationAlpha * (1f - sourceAlpha),
)
// (ONE, ONE) color, (ZERO, ONE) alpha.
BlendMode.AdditivePremultiplied ->
floatArrayOf(
srcPremul[0] + dstPremul[0],
srcPremul[1] + dstPremul[1],
srcPremul[2] + dstPremul[2],
destinationAlpha,
)
// (DST_COLOR, ONE_MINUS_SRC_ALPHA) color, (ZERO, ONE) alpha.
else ->
floatArrayOf(
srcPremul[0] * dstPremul[0] + dstPremul[0] * (1f - sourceAlpha),
srcPremul[1] * dstPremul[1] + dstPremul[1] * (1f - sourceAlpha),
srcPremul[2] * dstPremul[2] + dstPremul[2] * (1f - sourceAlpha),
destinationAlpha,
)
}
return FloatArray(4) { channelIndex -> out[channelIndex].coerceIn(0f, 1f) }
}
// Generic path: unpremultiply, blend, then weight the blended color by the overlap fraction
// w = p0/as, where p0 is the KHR advanced-blend overlap weight for the alpha mode's coverage
// model: as*ab uncorrelated (Over/Atop/Out), min(as, ab) conjoint (maximal overlap), and
// max(as + ab - 1, 0) disjoint (minimal overlap). The uncorrelated case reduces to the W3C
// backdrop-alpha weighting (w = ab). Then the alpha mode's Porter-Duff factors on
// premultiplied terms: co = as*Fa*Cm + ab*Fb*Cb, ao = as*Fa + ab*Fb.
val sourceColor = unpremultiply(srcPremul)
val destinationColor = unpremultiply(dstPremul)
val blended = blendColor(blendMode, destinationColor, sourceColor)
val overlap =
when (alphaBlendMode) {
AlphaBlendMode.Conjoint -> min(sourceAlpha, destinationAlpha)
AlphaBlendMode.Disjoint -> max(sourceAlpha + destinationAlpha - 1f, 0f)
else -> sourceAlpha * destinationAlpha
}
val blendWeight = if (sourceAlpha > 0f) overlap / sourceAlpha else 0f
val mixed =
FloatArray(3) { channelIndex ->
(1f - blendWeight) * sourceColor[channelIndex] + blendWeight * blended[channelIndex]
}
val sourceFactor: Float
val destinationFactor: Float
when (alphaBlendMode) {
AlphaBlendMode.Over -> {
sourceFactor = 1f
destinationFactor = 1f - sourceAlpha
}
AlphaBlendMode.Atop -> {
sourceFactor = destinationAlpha
destinationFactor = 1f - sourceAlpha
}
// DST-out: the source erases the destination where it covers (ao = ab*(1-as)); Fa = 0 so
// the source contributes no color of its own.
AlphaBlendMode.Out -> {
sourceFactor = 0f
destinationFactor = 1f - sourceAlpha
}
// X Render conjoint over: maximal overlap - the destination shows only where it exceeds
// the source (ao = max(as, ab)).
AlphaBlendMode.Conjoint -> {
sourceFactor = 1f
destinationFactor = if (destinationAlpha <= 0f || sourceAlpha >= destinationAlpha) 0f else 1f - sourceAlpha / destinationAlpha
}
// X Render disjoint over: minimal overlap - the coverages pack side by side
// (ao = min(1, as + ab)).
AlphaBlendMode.Disjoint -> {
sourceFactor = 1f
destinationFactor = if (destinationAlpha <= 0f) 0f else min(1f, (1f - sourceAlpha) / destinationAlpha)
}
}
val outAlpha = sourceAlpha * sourceFactor + destinationAlpha * destinationFactor
return floatArrayOf(
(sourceAlpha * sourceFactor * mixed[0] + destinationAlpha * destinationFactor * destinationColor[0]).coerceIn(0f, 1f),
(sourceAlpha * sourceFactor * mixed[1] + destinationAlpha * destinationFactor * destinationColor[1]).coerceIn(0f, 1f),
(sourceAlpha * sourceFactor * mixed[2] + destinationAlpha * destinationFactor * destinationColor[2]).coerceIn(0f, 1f),
outAlpha.coerceIn(0f, 1f),
)
}
/** The straight-alpha color of a premultiplied pixel, clamped to [0,1] (0 where the alpha is 0). */
private fun unpremultiply(premul: FloatArray): FloatArray {
val alpha = premul[3]
if (alpha <= 0f) {
return floatArrayOf(0f, 0f, 0f)
}
return floatArrayOf(
(premul[0] / alpha).coerceIn(0f, 1f),
(premul[1] / alpha).coerceIn(0f, 1f),
(premul[2] / alpha).coerceIn(0f, 1f),
)
}
/**
* The color blend function B(Cb, Cs) for [blendMode], on straight-alpha colors.
*
* @param BlendMode blendMode The color mode.
* @param FloatArray backdrop Cb, straight RGB.
* @param FloatArray source Cs, straight RGB.
* @return FloatArray The blended color, straight RGB.
*/
public fun blendColor(blendMode: BlendMode, backdrop: FloatArray, source: FloatArray): FloatArray =
when (blendMode) {
BlendMode.Normal -> source.copyOf()
// The additive family reads as linear dodge (add) in the generic path; the legacy mode's
// fixed-function semantics apply only under Over (see compositeReference). Add (Glow) has
// been checked against the official editor via Model A and matches this shared formula;
// Add's modern (_TSL) variant shares it too but is unconfirmed against the editor.
BlendMode.AdditivePremultiplied, BlendMode.Additive, BlendMode.AdditiveGlow ->
perChannel(backdrop, source) { backdropChannel, sourceChannel -> min(1f, backdropChannel + sourceChannel) }
BlendMode.MultiplyPremultiplied, BlendMode.Multiply ->
perChannel(backdrop, source) { backdropChannel, sourceChannel -> backdropChannel * sourceChannel }
BlendMode.Darken -> perChannel(backdrop, source) { backdropChannel, sourceChannel -> min(backdropChannel, sourceChannel) }
BlendMode.Lighten -> perChannel(backdrop, source) { backdropChannel, sourceChannel -> max(backdropChannel, sourceChannel) }
BlendMode.Screen ->
perChannel(backdrop, source) { backdropChannel, sourceChannel ->
backdropChannel + sourceChannel - backdropChannel * sourceChannel
}
BlendMode.ColorBurn ->
perChannel(backdrop, source) { backdropChannel, sourceChannel ->
when {
backdropChannel >= 1f -> 1f
sourceChannel <= 0f -> 0f
else -> 1f - min(1f, (1f - backdropChannel) / sourceChannel)
}
}
BlendMode.LinearBurn ->
perChannel(backdrop, source) { backdropChannel, sourceChannel -> max(0f, backdropChannel + sourceChannel - 1f) }
BlendMode.ColorDodge ->
perChannel(backdrop, source) { backdropChannel, sourceChannel ->
when {
backdropChannel <= 0f -> 0f
sourceChannel >= 1f -> 1f
else -> min(1f, backdropChannel / (1f - sourceChannel))
}
}
BlendMode.Overlay -> perChannel(backdrop, source) { backdropChannel, sourceChannel -> hardLight(sourceChannel, backdropChannel) }
BlendMode.HardLight -> perChannel(backdrop, source) { backdropChannel, sourceChannel -> hardLight(backdropChannel, sourceChannel) }
BlendMode.SoftLight ->
perChannel(backdrop, source) { backdropChannel, sourceChannel ->
if (sourceChannel <= 0.5f) {
backdropChannel - (1f - 2f * sourceChannel) * backdropChannel * (1f - backdropChannel)
} else {
backdropChannel + (2f * sourceChannel - 1f) * (softLightD(backdropChannel) - backdropChannel)
}
}
BlendMode.LinearLight ->
perChannel(backdrop, source) { backdropChannel, sourceChannel ->
(backdropChannel + 2f * sourceChannel - 1f).coerceIn(0f, 1f)
}
BlendMode.Hue -> setLuminosity(setSaturation(source, saturation(backdrop)), luminosity(backdrop))
BlendMode.Color -> setLuminosity(source, luminosity(backdrop))
}
private inline fun perChannel(backdrop: FloatArray, source: FloatArray, operation: (Float, Float) -> Float): FloatArray =
FloatArray(3) { channelIndex -> operation(backdrop[channelIndex], source[channelIndex]) }
/** W3C hard-light: multiply below the midpoint of [selector], screen above it. */
private fun hardLight(base: Float, selector: Float): Float =
if (selector <= 0.5f) {
2f * selector * base
} else {
val screened = base + (2f * selector - 1f) - base * (2f * selector - 1f)
screened
}
/** W3C soft-light's D(x) helper. */
private fun softLightD(value: Float): Float =
if (value <= 0.25f) {
((16f * value - 12f) * value + 4f) * value
} else {
sqrt(value)
}
/** W3C Lum(C). */
private fun luminosity(color: FloatArray): Float = 0.3f * color[0] + 0.59f * color[1] + 0.11f * color[2]
/** W3C Sat(C). */
private fun saturation(color: FloatArray): Float =
max(color[0], max(color[1], color[2])) - min(color[0], min(color[1], color[2]))
/** W3C ClipColor(C): pulls out-of-range channels back toward the luminosity. */
private fun clipColor(color: FloatArray): FloatArray {
val lum = luminosity(color)
val minChannel = min(color[0], min(color[1], color[2]))
val maxChannel = max(color[0], max(color[1], color[2]))
var result = color
if (minChannel < 0f) {
val below = result
result = FloatArray(3) { channelIndex -> lum + (below[channelIndex] - lum) * lum / (lum - minChannel) }
}
if (maxChannel > 1f) {
val above = result
result = FloatArray(3) { channelIndex -> lum + (above[channelIndex] - lum) * (1f - lum) / (maxChannel - lum) }
}
return result
}
/** W3C SetLum(C, l). */
private fun setLuminosity(color: FloatArray, lum: Float): FloatArray {
val delta = lum - luminosity(color)
return clipColor(floatArrayOf(color[0] + delta, color[1] + delta, color[2] + delta))
}
/** W3C SetSat(C, s): rescales the mid channel between min and max, on sorted channels. */
private fun setSaturation(color: FloatArray, sat: Float): FloatArray {
val result = FloatArray(3)
val indices = intArrayOf(0, 1, 2).sortedBy { color[it] }
val minIndex = indices[0]
val midIndex = indices[1]
val maxIndex = indices[2]
if (color[maxIndex] > color[minIndex]) {
result[midIndex] = (color[midIndex] - color[minIndex]) * sat / (color[maxIndex] - color[minIndex])
result[maxIndex] = sat
}
return result
}
@@ -0,0 +1,87 @@
package org.umamo.render.puppet
import org.umamo.render.ContentBounds
import org.umamo.render.eval.DeformedGeometry
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.PuppetModel
/**
* The side of the square an empty model with no canvas frames, in world units: room to start drawing in,
* around the world origin, at a zoom where the grid reads as a grid.
*/
private const val EMPTY_FRAME_EXTENT = 1000f
/**
* Computes the world-space extent of a deformed pose's shown drawables - the framing `view.fit` frames to.
*
* Backend-neutral: a bounding box over already-deformed positions, so every renderer backend shares it
* rather than re-deriving it beside its own GPU calls.
*
* Hidden drawables are excluded deliberately: a hidden full-canvas guide image or background must not
* stretch the framing of a view it is not drawn in.
*
* @param DeformedGeometry geometry The CPU-evaluated pose to measure.
* @param Set<DrawableId> shownIds The drawables actually drawn (the resolved visibility cascade).
* @return ContentBounds? The extent, with each span floored at 1 so a degenerate model never divides by
* zero downstream; null when no shown drawable has a vertex, so there is nothing to measure.
* @note Null rather than a sentinel rectangle on purpose. The sweep starts from the float extremes, and a
* rectangle left there frames a camera at the edge of float range, where the grid has no precision
* left to draw with - a blank viewport. That is the FIRST frame of a new, empty document, and what
* Fit does once every drawable is hidden, so the caller must choose what to frame instead
* ([emptyContentBoundsOf]).
*/
internal fun contentBoundsOf(geometry: DeformedGeometry, shownIds: Set<DrawableId>): ContentBounds? {
var loX = Float.MAX_VALUE
var loY = Float.MAX_VALUE
var hiX = -Float.MAX_VALUE
var hiY = -Float.MAX_VALUE
for ((drawableId, world) in geometry.worldPositions) {
// A hidden full-canvas guide image / background must not stretch the framing it isn't drawn in.
if (drawableId !in shownIds) {
continue
}
var coordIndex = 0
while (coordIndex < world.size) {
loX = minOf(loX, world[coordIndex])
hiX = maxOf(hiX, world[coordIndex])
loY = minOf(loY, world[coordIndex + 1])
hiY = maxOf(hiY, world[coordIndex + 1])
coordIndex += 2
}
}
if (loX > hiX || loY > hiY) {
return null
}
return ContentBounds(loX, loY, maxOf(hiX - loX, 1f), maxOf(hiY - loY, 1f))
}
/**
* What a view frames when the model shows nothing to measure: the document's canvas, or - for a model that
* carries no canvas - a square around the world origin.
*
* The canvas is where the art will go, so it is the honest frame for a new, empty document and for a rig
* whose every drawable is hidden. World space is canvas x with canvas y negated, so a canvas spanning
* [0, width] x [0, height] occupies x in [0, width] and y in [-height, 0] here.
*
* @param PuppetModel model The model being framed.
* @return ContentBounds The rectangle to fit.
*/
internal fun emptyContentBoundsOf(model: PuppetModel): ContentBounds =
canvasBoundsOf(model)
?: ContentBounds(model.worldOriginX - EMPTY_FRAME_EXTENT / 2f, model.worldOriginZ - EMPTY_FRAME_EXTENT / 2f, EMPTY_FRAME_EXTENT, EMPTY_FRAME_EXTENT)
/**
* The document's canvas rectangle in world space, or null for a model that carries no canvas.
*
* World space is canvas x with canvas y negated, so a canvas spanning [0, width] x [0, height] occupies
* x in [0, width] and y in [-height, 0] here.
*
* @param PuppetModel model The model whose canvas to place.
* @return ContentBounds? The canvas rectangle, or null when either canvas dimension is not positive.
*/
fun canvasBoundsOf(model: PuppetModel): ContentBounds? =
if (model.canvasWidth > 0f && model.canvasHeight > 0f) {
ContentBounds(0f, -model.canvasHeight, model.canvasWidth, model.canvasHeight)
} else {
null
}
@@ -0,0 +1,172 @@
package org.umamo.render.puppet
import org.umamo.runtime.eval.cellsByLinearIndex
import org.umamo.runtime.eval.meshGridDefaultDeltas
import org.umamo.runtime.keyform.cellCount
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshDeltaForm
import org.umamo.runtime.model.ParameterId
/**
* The linear cell extent of a keyform grid - the product of each axis's key count.
*
* This is the delta texture's width: one column per keyform cell, addressed by the cell's linear index
* (the same index [org.umamo.runtime.eval.WeightedCell.linearIndex] carries, which is how the vertex
* shader's active corners find their column).
*
* A null grid is an UNKEYED drawable and gets a single column, which the texel build fills with zeros -
* so the shader fetches column 0 at full weight and reads no offset, leaving the mesh at rest. That is
* what lets an unkeyed drawable render with no shader, uniform-layout, or RenderDevice change at all.
*
* @param KeyformGrid? grid The mesh's keyform grid, or null when the drawable is unkeyed.
* @return Int The cell count, floored at 1 so an axis-less or absent grid still gets its single rest cell.
*/
internal fun keyformCellCount(grid: KeyformGrid<MeshDeltaForm>?): Int = maxOf(1, grid?.cellCount ?: 1)
/**
* Builds a mesh's per-keyform-cell vertex deltas as RG texels: row = vertex id, column = cell linear
* index, RG = (Δx, Δy). This is the `p = base + Σ wᵢ·Δᵢ` morph's Δ table, which the vertex shader
* texel-fetches per active corner.
*
* Backend-neutral by construction: it returns plain texels, so each backend uploads them its own way
* (an RG32F 2D texture on the GL family; whatever Metal prefers). Emitting a backend's buffer type here
* would put a texture-upload decision in shared code.
*
* A cell with no keyform, or one whose delta array is too short for this vertex, contributes (0, 0) -
* i.e. that cell leaves the vertex at its rest position. Both cases are reachable in real models, so
* they are a normal absence rather than an error.
*
* @param KeyformGrid? grid The mesh's keyform grid, or null when the drawable is unkeyed (which
* yields an all-zero single column - the rest mesh).
* @param Int vertexCount The mesh's vertex count (the texture height).
* @param Int cellCount The grid's linear cell extent from [keyformCellCount] (the width).
* @param Map cells The grid's cells by linear index; defaults to [cellsByLinearIndex] of
* [grid], but a caller that already built the map (the drawable upload also needs it for the composite
* bounds walk) can pass it in to avoid rebuilding it.
* @return FloatArray The texels, row-major, length `vertexCount * cellCount * 2`.
*/
internal fun buildDeltaTexels(
grid: KeyformGrid<MeshDeltaForm>?,
vertexCount: Int,
cellCount: Int,
cells: Map<Int, KeyformCell<MeshDeltaForm>> = if (grid != null) cellsByLinearIndex(grid) else emptyMap(),
): FloatArray {
val texels = FloatArray(vertexCount * cellCount * 2)
var writeIndex = 0
for (vertexIndex in 0 until vertexCount) {
for (cellIndex in 0 until cellCount) {
val deltas = cells[cellIndex]?.form?.positionDeltas
if (deltas != null && vertexIndex * 2 + 1 < deltas.size) {
texels[writeIndex] = deltas[vertexIndex * 2]
texels[writeIndex + 1] = deltas[vertexIndex * 2 + 1]
}
// else: leave (0, 0) - a missing cell or a short delta array means no offset from rest.
writeIndex += 2
}
}
return texels
}
/**
* The static column assignment of a drawable's blend-shape delta forms in its delta texture:
* blend columns are appended after the grid's [cellCount] columns, in (binding order, key order),
* skipping neutral/absent forms (their delta is zero and never fetched). CPU pose prep, the texel
* bake, and the per-frame uniform fill all agree through this one mapping.
*
* @property Int cellCount The grid's own column count (blend columns start here).
* @property Int blendColumnCount Number of appended blend columns.
*/
internal class BlendColumnLayout(
val cellCount: Int,
val blendColumnCount: Int,
private val columnByKey: Map<Long, Int>,
) {
/**
* The texture column of one binding's key form, or null when that key holds no form (neutral).
*
* @param Int bindingIndex Index into the drawable's blendShapes.
* @param Int keyIndex Key index within that binding.
* @return Int? The absolute texture column, or null.
*/
fun columnOf(bindingIndex: Int, keyIndex: Int): Int? = columnByKey[packKey(bindingIndex, keyIndex)]
internal companion object {
/** Packs a (binding, key) pair into one map key. */
internal fun packKey(bindingIndex: Int, keyIndex: Int): Long = bindingIndex.toLong() shl 32 or keyIndex.toLong()
}
}
/**
* Builds the blend-column layout for [drawable] over a grid of [cellCount] columns.
*
* @param Drawable drawable The drawable (its blendShapes define the columns).
* @param Int cellCount The grid's own column count.
* @return BlendColumnLayout The layout (zero blend columns when binding-free).
*/
internal fun blendColumnLayout(drawable: Drawable, cellCount: Int): BlendColumnLayout {
val columnByKey = HashMap<Long, Int>()
var nextColumn = cellCount
for (bindingIndex in drawable.blendShapes.indices) {
val binding = drawable.blendShapes[bindingIndex]
for (keyIndex in binding.forms.indices) {
if (binding.forms[keyIndex] != null) {
columnByKey[BlendColumnLayout.packKey(bindingIndex, keyIndex)] = nextColumn
nextColumn++
}
}
}
return BlendColumnLayout(cellCount, nextColumn - cellCount, columnByKey)
}
/**
* Builds a mesh's delta texels INCLUDING its appended blend-shape columns: the grid columns as
* [buildDeltaTexels], then one column per non-neutral blend form holding the E5-resolved delta
* (form minus the grid-at-default reference) per vertex. Static per model, like the grid columns.
*
* @param KeyformGrid grid The mesh's keyform grid.
* @param Drawable drawable The drawable (blend forms + reference resolution).
* @param Function defaultValue Default value per parameter id (the reference pose).
* @param Int vertexCount The mesh's vertex count (the texture height).
* @param BlendColumnLayout layout The column assignment from [blendColumnLayout].
* @param Map cells The grid's cells by linear index; defaults to [cellsByLinearIndex]
* of [grid], but a caller that already built the map can pass it in to avoid rebuilding it.
* @return FloatArray The texels, row-major, length `vertexCount * (cellCount + blendColumnCount) * 2`.
*/
internal fun buildDeltaTexelsWithBlend(
grid: KeyformGrid<MeshDeltaForm>?,
drawable: Drawable,
defaultValue: (ParameterId) -> Float,
vertexCount: Int,
layout: BlendColumnLayout,
cells: Map<Int, KeyformCell<MeshDeltaForm>> = if (grid != null) cellsByLinearIndex(grid) else emptyMap(),
): FloatArray {
val width = layout.cellCount + layout.blendColumnCount
val texels = FloatArray(vertexCount * width * 2)
val reference = meshGridDefaultDeltas(drawable, defaultValue)
for (vertexIndex in 0 until vertexCount) {
val rowBase = vertexIndex * width * 2
for (cellIndex in 0 until layout.cellCount) {
val deltas = cells[cellIndex]?.form?.positionDeltas
if (deltas != null && vertexIndex * 2 + 1 < deltas.size) {
texels[rowBase + cellIndex * 2] = deltas[vertexIndex * 2]
texels[rowBase + cellIndex * 2 + 1] = deltas[vertexIndex * 2 + 1]
}
}
for (bindingIndex in drawable.blendShapes.indices) {
val binding = drawable.blendShapes[bindingIndex]
for (keyIndex in binding.forms.indices) {
val form = binding.forms[keyIndex] ?: continue
val column = layout.columnOf(bindingIndex, keyIndex) ?: continue
if (vertexIndex * 2 + 1 < form.positionDeltas.size) {
val referenceX = reference?.getOrNull(vertexIndex * 2) ?: 0f
val referenceY = reference?.getOrNull(vertexIndex * 2 + 1) ?: 0f
texels[rowBase + column * 2] = form.positionDeltas[vertexIndex * 2] - referenceX
texels[rowBase + column * 2 + 1] = form.positionDeltas[vertexIndex * 2 + 1] - referenceY
}
}
}
}
return texels
}
@@ -0,0 +1,23 @@
package org.umamo.render.puppet
/**
* A stable, readable flat color for an untextured drawable, derived from its id.
*
* Only reached when a drawable resolves to no atlas page, so it is a development affordance rather than
* anything a rigger sees in a textured model - it exists so an untextured mesh is visible and tellable
* apart from its neighbours instead of rendering invisible. Hashing the id (rather than cycling a
* palette by index) keeps a given drawable the same color across reorders and reloads.
*
* The channel floor of 0.35 and the 0.6 span keep every result mid-bright: dark enough to read against
* the light grid, light enough against the dark one.
*
* @param String id The drawable's raw id.
* @return FloatArray RGBA, each 0..1, at a fixed 0.85 alpha.
*/
internal fun fallbackColorFor(id: String): FloatArray {
val hash = id.hashCode()
val red = 0.35f + ((hash shr 16) and 0xFF) / 255f * 0.6f
val green = 0.35f + ((hash shr 8) and 0xFF) / 255f * 0.6f
val blue = 0.35f + (hash and 0xFF) / 255f * 0.6f
return floatArrayOf(red, green, blue, 0.85f)
}
@@ -0,0 +1,140 @@
package org.umamo.render.puppet
import org.umamo.render.glsl.MAX_GLUES
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.PuppetModel
/**
* One glue mesh's per-vertex weld attributes, parallel arrays indexed by the mesh's own vertex index.
*
* A vertex that is not glued points at ITSELF with weight 0 - a weld that is arithmetically a no-op
* (`own + (own - own) * 0`), which is why the shader needs no "is this vertex glued" branch beyond the
* cheap [glueIndex] test.
*
* Three arrays rather than one packed byte blob deliberately. The packed form is a GL vertex-attribute
* layout (12 bytes/vertex, native byte order), and encoding it here would put a backend's memory layout
* into shared code AND force this module to invent an endianness convention that the GL side would then
* have to honor silently. What each vertex welds to is shared; how the bytes sit is the backend's.
*
* @property IntArray partnerIndex Per vertex: the partner's GLOBAL index in the shared position store,
* or the vertex's own global index when it is not glued.
* @property IntArray glueIndex Per vertex: which glue supplies the per-pose intensity, or -1 when
* not glued.
* @property FloatArray weldWeight Per vertex: how far to move toward the partner (0 when not glued).
*/
public class GlueVertexAttributes(
val partnerIndex: IntArray,
val glueIndex: IntArray,
val weldWeight: FloatArray,
)
/**
* The addressing plan for a model's glue: who participates, where each mesh sits in the shared deformed
* position store, and what every vertex welds to.
*
* @property Set glueMeshIds Every mesh in any glue pair, INCLUDING zero-triangle anchors, which
* draw nothing but whose deformed positions are weld partners.
* @property Map baseOffsetById Each glue mesh's first vertex index in the shared store.
* @property Int globalVertexCount The store's total vertex capacity.
* @property Map attributesById Each glue mesh's per-vertex weld attributes.
*/
internal class GlueLayout(
val glueMeshIds: Set<DrawableId>,
val baseOffsetById: Map<DrawableId, Int>,
val globalVertexCount: Int,
val attributesById: Map<DrawableId, GlueVertexAttributes>,
)
/**
* Plans [model]'s glue addressing: the participating meshes, their base offsets in the shared deformed
* position store, and every vertex's weld attributes.
*
* Backend-neutral - it decides WHAT welds to what, in terms of vertex indices, and nothing about how a
* GPU stores it.
*
* The offsets are assigned by walking [PuppetModel.drawables] in order and giving each glue mesh the next
* region, so that iteration order DEFINES the addressing. Both the GPU write (pass 1 deforms each mesh
* into its own region) and the GPU read (pass 2 fetches a partner by global index) depend on producer and
* consumer agreeing on it exactly.
*
* @param PuppetModel model The rig.
* @return GlueLayout The addressing plan; empty throughout when the model has no glue.
* @note A glue pair whose vertex index is outside its mesh throws here, whereas the CPU weld
* (`applyGluesResolved`) silently skips it. That divergence predates this extraction and is preserved
* rather than quietly papered over - a malformed pair should be dealt with deliberately, not by two
* different behaviours in two backends.
*/
internal fun planGlueLayout(model: PuppetModel): GlueLayout {
val glueMeshIds = HashSet<DrawableId>()
for (glue in model.glues) {
glueMeshIds.add(glue.meshA)
glueMeshIds.add(glue.meshB)
}
val vertexCountById = HashMap<DrawableId, Int>(glueMeshIds.size)
val baseOffsetById = HashMap<DrawableId, Int>(glueMeshIds.size)
var globalVertexCount = 0
// model.drawables order defines the offsets - see the docblock.
for (drawable in model.drawables) {
if (drawable.id !in glueMeshIds) {
continue
}
val vertexCount = (drawable.mesh?.positions?.size ?: 0) / 2
vertexCountById[drawable.id] = vertexCount
baseOffsetById[drawable.id] = globalVertexCount
globalVertexCount += vertexCount
}
// Every vertex starts as an un-glued no-op weld: partner = self, no glue, zero weight.
val attributesById = HashMap<DrawableId, GlueVertexAttributes>(glueMeshIds.size)
for (id in glueMeshIds) {
val base = baseOffsetById[id] ?: continue // a glue naming a drawable the model does not carry
val vertexCount = vertexCountById[id] ?: continue
attributesById[id] =
GlueVertexAttributes(
partnerIndex = IntArray(vertexCount) { vertexIndex -> base + vertexIndex },
glueIndex = IntArray(vertexCount) { -1 },
weldWeight = FloatArray(vertexCount),
)
}
// Then each pair points both members at each other, by global index.
for ((glueIndex, glue) in model.glues.withIndex()) {
// glue #65+ has no slot in the shader's fixed glueIntensity[MAX_GLUES] uniform array, and a
// vertex tagged with it would index that array out of bounds. Leave those vertices at their -1
// (unwelded) default rather than tag them - this is what makes resolvePose's "renders unwelded"
// promise actually true.
if (glueIndex >= MAX_GLUES) {
continue
}
val baseA = baseOffsetById[glue.meshA] ?: continue
val baseB = baseOffsetById[glue.meshB] ?: continue
val attributesA = attributesById[glue.meshA] ?: continue
val attributesB = attributesById[glue.meshB] ?: continue
for (pair in glue.pairs) {
writeGlueVertex(attributesA, pair.indexA, baseB + pair.indexB, glueIndex, pair.weightA)
writeGlueVertex(attributesB, pair.indexB, baseA + pair.indexA, glueIndex, pair.weightB)
}
}
return GlueLayout(glueMeshIds, baseOffsetById, globalVertexCount, attributesById)
}
/**
* Points one vertex at its weld partner.
*
* @param GlueVertexAttributes attributes The owning mesh's attributes.
* @param Int vertexIndex The vertex, in its own mesh's indexing.
* @param Int partnerGlobalIndex The partner's index in the shared store.
* @param Int glueIndex Which glue supplies the per-pose intensity.
* @param Float weight How far to move toward the partner.
*/
private fun writeGlueVertex(
attributes: GlueVertexAttributes,
vertexIndex: Int,
partnerGlobalIndex: Int,
glueIndex: Int,
weight: Float,
) {
attributes.partnerIndex[vertexIndex] = partnerGlobalIndex
attributes.glueIndex[vertexIndex] = glueIndex
attributes.weldWeight[vertexIndex] = weight
}
@@ -0,0 +1,145 @@
package org.umamo.render.puppet
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.PuppetModel
/**
* What a backend must do to one drawable to reconcile its residency with an edited model.
*
* The decision, not the doing: which tier a drawable falls into is backend-neutral, while freeing GPU
* objects and re-uploading buffers is the backend's.
*/
internal sealed interface DrawableAction {
/** The drawable this action concerns. */
val drawableId: DrawableId
/**
* The backend has never seen this drawable - an Object-mode duplicate, or one skipped at load for
* having no geometry. Upload it whole. Never part of the load-time glue layout, so it welds nothing.
*/
class Upload(val drawable: Drawable) : DrawableAction {
override val drawableId: DrawableId get() = drawable.id
}
/**
* The topology changed (vertex count, indices, the keyform grid, or the blend-shape bindings), or
* the drawable was reparented across the warp boundary (gaining or losing a control-point texture),
* so every buffer and the delta texture are stale. Free the resident and upload it whole against
* the new mesh.
*/
class Reupload(val drawable: Drawable) : DrawableAction {
override val drawableId: DrawableId get() = drawable.id
}
/**
* The residency is reusable. Non-null [positions] / [uvs] are in-place re-uploads for the tiers that
* changed; both null means no BUFFER work - but the resident's static composite state (blend/alpha
* mode, culling, mask ids, invert) is still re-stamped from [drawable], since a composite-only edit
* changes no mesh array and so lands here, not in Reupload.
*/
class Keep(
val drawable: Drawable,
val positions: FloatArray?,
val uvs: FloatArray?,
) : DrawableAction {
override val drawableId: DrawableId get() = drawable.id
}
}
/**
* A reconcile plan: what to do with each drawable, and which residents to free.
*
* @property List actions Per-drawable actions in [PuppetModel.drawables] order, so applying them in
* sequence rebuilds residency in that same order.
* @property List removed Resident ids the edit dropped entirely; free them after applying [actions].
*/
internal class ModelDiff(
val actions: List<DrawableAction>,
val removed: List<DrawableId>,
)
/**
* Decides how to reconcile a backend's resident drawables with an edited model - four tiers, cheapest
* first.
*
* A layer reorder or a reparent that does not change control-point ownership needs no buffer work at all
* (every drawable is a no-op [Keep]); a base-mesh move re-uploads positions; a UV edit re-uploads UVs; and
* a structural change - a drawable added, removed, remeshed, its blend-shape bindings changed, or
* reparented across the warp boundary (which gains or loses its control-point texture) - frees and
* re-uploads whole.
*
* The diff is keyed by drawable id (so it is robust to a simultaneous reorder) and by ARRAY REFERENCE
* identity: the edit path is copy-on-write, so an untouched drawable keeps its exact array instances and
* is skipped by an `!==` test without comparing any element.
*
* @param PuppetModel model The model the residency currently reflects.
* @param PuppetModel newModel The edited model.
* @param Map residentVertexCountById Each resident drawable's uploaded vertex count. An INPUT
* rather than something derived from [model], and deliberately so: a drawable whose mesh went null is
* kept resident, after which [model] no longer carries the count its buffers were built at - only the
* backend still knows it. Its keys are also the authoritative "what is resident" set, which is not the
* same as [model]'s drawables (one with no geometry is skipped at upload).
* @return ModelDiff The reconcile plan.
* @pre Call BEFORE reassigning the backend's current model - the diff reads [model] as the state the
* GPU buffers still match.
*/
internal fun diffModel(
model: PuppetModel,
newModel: PuppetModel,
residentVertexCountById: Map<DrawableId, Int>,
): ModelDiff {
val oldDrawableById = model.drawables.associateBy { it.id }
// Warp parenting decides whether a drawable owns a control-point texture, and that is fixed at upload:
// a reparent that flips it (deleting a rotation deformer between a drawable and a warp, say) leaves a
// resident whose cp texture is stale or absent, so it must re-upload, not Keep. Derived purely from the
// two models - residency === `model`, so the old warp set matches what the backend actually uploaded.
val oldWarpIds = model.deformers.filterIsInstance<Deformer.Warp>().mapTo(HashSet()) { it.id }
val newWarpIds = newModel.deformers.filterIsInstance<Deformer.Warp>().mapTo(HashSet()) { it.id }
val actions = ArrayList<DrawableAction>(newModel.drawables.size)
for (drawable in newModel.drawables) {
val residentVertexCount = residentVertexCountById[drawable.id]
if (residentVertexCount == null) {
actions.add(DrawableAction.Upload(drawable))
continue
}
val newMesh = drawable.mesh
val oldDrawable = oldDrawableById[drawable.id]
val oldMesh = oldDrawable?.mesh
val warpParentingFlipped =
(oldDrawable != null && oldDrawable.parentDeformerId in oldWarpIds) != (drawable.parentDeformerId in newWarpIds)
val remeshed =
warpParentingFlipped ||
(
newMesh != null &&
(
newMesh.positions.size != residentVertexCount * 2 ||
(oldMesh != null && newMesh.indices !== oldMesh.indices) ||
drawable.geometryGrid !== oldDrawable?.geometryGrid ||
// Blend-shape deltas are baked into the delta texture's appended
// columns, so a binding change invalidates the texture layout.
drawable.blendShapes !== oldDrawable?.blendShapes
)
)
if (remeshed) {
actions.add(DrawableAction.Reupload(drawable))
continue
}
if (newMesh == null || oldMesh == null) {
actions.add(DrawableAction.Keep(drawable, positions = null, uvs = null))
continue
}
val positions = newMesh.positions.takeIf { it !== oldMesh.positions }
// The length guard is defensive: the copy-on-write UV edit never changes the array length, so a
// mismatch can only mean a mesh the backend padded at upload - leave that resident's UVs alone.
val uvs = newMesh.uvs.takeIf { it !== oldMesh.uvs && it.size == residentVertexCount * 2 }
actions.add(DrawableAction.Keep(drawable, positions, uvs))
}
// Anything resident with no action is gone from the model. A Reupload is an ACTION, so a drawable that
// is freed and then fails to re-upload cannot also appear here - which is what stops the free happening
// twice, and with it the chance of the second free hitting a GL name the driver has since recycled.
val actioned = actions.mapTo(HashSet(actions.size)) { it.drawableId }
val removed = residentVertexCountById.keys.filter { it !in actioned }
return ModelDiff(actions, removed)
}
@@ -0,0 +1,29 @@
package org.umamo.render.puppet
/**
* Reverses an RGBA8888 image's row order into a fresh buffer.
*
* The bridge between a bottom-up framebuffer read-back and the top-first convention every consumer
* here uses (`org.umamo.format.raster.RasterImage`, and the layered readers' pixel form). OpenGL's
* `glReadPixels` returns the bottom row first, so its device's read-back flips through this; a
* top-left-origin backend (Metal) does not. Which way up a backend reads is therefore a fact confined
* to that backend, and no caller of `readPixels` ever asks.
*
* Row-wise, not per-pixel: the channel order is already what the caller wants, so only the row
* ordering changes.
*
* @param ByteArray rgba The source pixels, RGBA8888, tightly packed, `width * height * 4` bytes.
* @param Int width The image width in pixels.
* @param Int height The image height in pixels.
* @return ByteArray A new buffer with the row order reversed.
*/
internal fun flipRowsVertically(rgba: ByteArray, width: Int, height: Int): ByteArray {
val rowBytes = width * 4
val flipped = ByteArray(rgba.size)
for (rowIndex in 0 until height) {
val sourceStart = rowIndex * rowBytes
val destinationStart = (height - 1 - rowIndex) * rowBytes
rgba.copyInto(flipped, destinationStart, sourceStart, sourceStart + rowBytes)
}
return flipped
}
@@ -0,0 +1,159 @@
package org.umamo.render.puppet
import org.umamo.render.eval.DeformerWorld
import org.umamo.render.eval.MeshBlendState
import org.umamo.render.eval.PoseDeformInputs
import org.umamo.render.eval.RenderPlanComposite
import org.umamo.render.eval.RenderPlanDrawable
import org.umamo.render.eval.RenderPlanNode
import org.umamo.render.eval.flattenRenderPlan
import org.umamo.render.eval.paintOrder
import org.umamo.render.eval.renderPlan
import org.umamo.render.glsl.MAX_GLUES
import org.umamo.runtime.eval.WeightedCell
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.RenderGroup
/**
* One drawable's resolved per-pose deform state - what the backend must hand its shaders to draw it.
*
* @property DrawableId drawableId The drawable.
* @property List corners The active keyform-grid corners and their blend weights.
* @property DeformerWorld parentWorld The baked parent-deformer transform, or null for a direct mesh.
* @property Float opacity The pose-blended opacity.
*/
internal class PosedDrawable(
val drawableId: DrawableId,
val corners: List<WeightedCell>,
val parentWorld: DeformerWorld?,
val opacity: Float,
val multiplyColor: ColorRgb = ColorRgb.MultiplyIdentity,
val screenColor: ColorRgb = ColorRgb.ScreenIdentity,
val blend: MeshBlendState? = null,
)
/**
* A pose resolved against what a backend actually has resident.
*
* @property Map posed Every drawable that produced geometry this pose, in
* [PoseDeformInputs.drawables] order. This is a SUPERSET of what is drawn: it includes index-less glue
* anchors and hidden mask sources, both of which must still deform.
* @property List renderPlan The drawn drawables in resolved back-to-front order WITH the
* isolated group boundaries preserved ([RenderPlanComposite] nodes) - what a compositing renderer
* walks. Filtered like [drawOrder]; a composite node whose subtree filtered to empty is dropped.
* @property List drawOrder The drawn drawables, back-to-front (last = front): posed AND
* renderable AND shown, in resolved render order. Always equals the flattened [renderPlan].
* @property FloatArray glueIntensities Per-glue weld intensity by glue index, length [MAX_GLUES].
*/
internal class ResolvedPose(
val posed: Map<DrawableId, PosedDrawable>,
val renderPlan: List<RenderPlanNode>,
val drawOrder: List<DrawableId>,
val glueIntensities: FloatArray,
)
/**
* Resolves a prepared pose against a backend's residency: which drawables deform, which are actually
* drawn and in what order, and each glue's weld intensity.
*
* Backend-neutral - it decides WHAT to draw, never how. The one thing it needs from the backend is
* [renderableById], because "posed" and "drawn" are genuinely different questions and only the backend
* knows the answer to the second.
*
* @param PoseDeformInputs inputs The prepared per-pose inputs.
* @param Map renderableById Resident drawable id → whether it carries triangles. The KEYS
* are the residency set (a drawable the backend never uploaded cannot pose); the VALUE says whether it
* draws anything. The two differ: an index-less glue anchor is resident and poses - its deformed
* positions are a weld partner - but renders nothing.
* @param Set shownIds The resolved Parts-panel visibility cascade.
* @param List baseOrder The model's flat drawable order, for a group-less model.
* @param RenderGroup renderRoot The draw-order group tree.
* @param FloatArray glueIntensities A caller-owned array of length [MAX_GLUES] this fills in place
* (and returns in [ResolvedPose.glueIntensities]), so a per-pose render allocates no intensity buffer.
* @return ResolvedPose The pose, resolved.
*/
internal fun resolvePose(
inputs: PoseDeformInputs,
renderableById: Map<DrawableId, Boolean>,
shownIds: Set<DrawableId>,
baseOrder: List<DrawableId>,
renderRoot: RenderGroup,
glueIntensities: FloatArray,
): ResolvedPose {
// LinkedHashMap: iteration follows inputs.drawables order, which the backend's per-pose uploads walk.
val posed = LinkedHashMap<DrawableId, PosedDrawable>(inputs.drawables.size)
val drawOrderById = HashMap<DrawableId, Float>(inputs.drawables.size)
for (drawableInputs in inputs.drawables) {
if (drawableInputs.drawableId !in renderableById) {
continue // not resident: the backend has nothing to draw it with
}
val corners = drawableInputs.corners ?: continue // hidden at this pose
if (drawableInputs.isParented && drawableInputs.parentWorld == null) {
continue // a hidden ancestor deformer produced no transform, so the mesh has no geometry
}
posed[drawableInputs.drawableId] =
PosedDrawable(
drawableInputs.drawableId,
corners,
drawableInputs.parentWorld,
drawableInputs.opacity,
drawableInputs.multiplyColor,
drawableInputs.screenColor,
drawableInputs.blend,
)
drawOrderById[drawableInputs.drawableId] = drawableInputs.drawOrder
}
// Weld intensity per pose, gated on BOTH meshes being posed. Pass 1 only writes a posed glue mesh's
// region of the shared position store; if a partner is unposed its region is uninitialised, so welding
// toward it would read garbage (random spikes on a live, dirty GPU). A zero intensity makes the weld
// skip the partner read entirely - matching the CPU applyGluesResolved, which skips a glue whose
// partner produced no geometry. Note this asks whether the partner POSED, not whether it draws: an
// index-less anchor is a legitimate partner.
glueIntensities.fill(1f) // slots beyond glues.size stay 1f and are never read by the shader
for ((glueIndex, glue) in inputs.glues.withIndex()) {
if (glueIndex >= MAX_GLUES) {
continue // beyond the shader's glueIntensity[] array: this glue renders unwelded
}
val bothPosed = glue.meshA in posed && glue.meshB in posed
glueIntensities[glueIndex] = if (bothPosed) glue.intensity else 0f
}
// Hierarchical render plan over the draw-order group tree (with per-pose animated part order); the
// flat base order when the model carries no groups. The drawn-filter applies to the PLAN (an
// isolated subtree that filters to empty disappears with its composite), and the flat draw order
// is its flattening - the two views can never disagree.
val plan =
if (renderRoot.children.isEmpty()) {
paintOrder(baseOrder, drawOrderById).map(::RenderPlanDrawable)
} else {
renderPlan(renderRoot, drawOrderById, inputs.partDrawOrders)
}
val drawnPlan = filterPlan(plan) { it in posed && renderableById[it] == true && it in shownIds }
return ResolvedPose(posed, drawnPlan, flattenRenderPlan(drawnPlan), glueIntensities)
}
/**
* Filters a render plan's drawable leaves by [isDrawn], dropping a composite node whose whole
* subtree filtered away (compositing an empty layer would be a wasted pass, and the visibility
* cascade lands here - a hidden part's drawables all fail the shown filter).
*
* @param List<RenderPlanNode> nodes The plan nodes.
* @param Function isDrawn Whether a drawable is actually drawn this pose.
* @return List<RenderPlanNode> The filtered plan.
*/
private fun filterPlan(nodes: List<RenderPlanNode>, isDrawn: (DrawableId) -> Boolean): List<RenderPlanNode> =
nodes.mapNotNull { node ->
when (node) {
is RenderPlanDrawable -> node.takeIf { isDrawn(it.id) }
is RenderPlanComposite -> {
val children = filterPlan(node.children, isDrawn)
if (children.isEmpty()) {
null
} else {
RenderPlanComposite(node.partId, node.composite, children)
}
}
}
}
@@ -0,0 +1,125 @@
package org.umamo.render.puppet
import org.umamo.render.eval.DeformerWorld
import org.umamo.render.eval.MeshBlendState
import org.umamo.runtime.eval.WeightedCell
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.MeshDeltaForm
import kotlin.math.max
import kotlin.math.min
/*
* Exact per-pose drawable world bounds - the screen rectangle the composite scissor is built from.
*
* The renderer confines a composite layer's clear, destination snapshot, and composite draw to the
* isolated subtree's screen rect, so an isolated group costs fill proportional to its own extent
* rather than the whole viewport. Conservatism is the whole contract: an undersized bound clips
* rendered pixels (a head-top or an arm past its warp lattice would vanish), so this evaluates the
* SAME deform the shader does - `base + Sigma w_i * delta_i`, plus blend-shape deltas, through the
* parent deformer, then the Y negation - and takes the true AABB of the deformed vertices. A cheap
* analytic lattice bound was tried and abandoned: a warp deformer's out-of-lattice extrapolation is
* piecewise and does not decompose into a conservative closed form, so it undersized at the extremes.
*
* The per-vertex walk is allocation-free (a running min/max plus a 2-float transform scratch) and the
* cells map is precomputed once at upload, so it costs only the composited drawables' vertices per
* pose - a fraction of a full CPU deform, and dwarfed by the fill it saves.
*/
/** An axis-aligned bounding rectangle in the renderer's post-Y-negation world space. */
internal class PosedAabb(
val minX: Float,
val minY: Float,
val maxX: Float,
val maxY: Float,
)
/**
* The exact deformed-world AABB of one drawable at the current pose: the keyform-blended local
* vertices (plus blend-shape deltas) pushed through [parentWorld] and Y-negated, min/maxed. Mirrors
* `deformMeshWorldFromCorners` component for component so the bound can never disagree with the
* rendered geometry. Returns null when the mesh is empty.
*
* @param FloatArray base The mesh's rest positions, interleaved x,y.
* @param Map<Int, KeyformCell<MeshDeltaForm>> cells The grid's cells by linear index (precomputed once).
* @param List<WeightedCell> corners The pose's active keyform corners and weights.
* @param DeformerWorld? parentWorld The baked parent transform, or null for a direct mesh.
* @param MeshBlendState? blend The pose's resolved blend-shape state, or null.
* @return PosedAabb? The world bounds, or null when the mesh has no vertices or a vertex deforms to a
* non-finite position (an unusable bound the renderer treats as "no bound", keeping the full-viewport path).
*/
internal fun deformedWorldBounds(
base: FloatArray,
cells: Map<Int, KeyformCell<MeshDeltaForm>>,
corners: List<WeightedCell>,
parentWorld: DeformerWorld?,
blend: MeshBlendState?,
): PosedAabb? {
val vertexCount = base.size / 2
if (vertexCount == 0) {
return null
}
var minX = Float.POSITIVE_INFINITY
var minY = Float.POSITIVE_INFINITY
var maxX = Float.NEGATIVE_INFINITY
var maxY = Float.NEGATIVE_INFINITY
val scratch = FloatArray(2)
for (vertexIndex in 0 until vertexCount) {
val componentX = vertexIndex * 2
val componentY = componentX + 1
var localX = base[componentX]
var localY = base[componentY]
// The multilinear keyform blend: base + Sigma w_i * delta_i (a missing cell or short delta
// array contributes zero, exactly as buildDeltaTexels and blendLocalFromCorners treat it).
for (corner in corners) {
val deltas = cells[corner.linearIndex]?.form?.positionDeltas ?: continue
if (componentY < deltas.size) {
localX += corner.weight * deltas[componentX]
localY += corner.weight * deltas[componentY]
}
}
// Blend shapes: additive per-vertex deltas relative to the grid-at-default reference, on top
// of the grid blend, before the parent transform - the exact deformMeshWorldFromCorners loop.
if (blend != null) {
for (contribution in blend.contributions) {
val deltas = contribution.form.positionDeltas
if (componentY < deltas.size) {
val referenceX = blend.referenceDeltas?.getOrNull(componentX) ?: 0f
val referenceY = blend.referenceDeltas?.getOrNull(componentY) ?: 0f
localX += contribution.weight * (deltas[componentX] - referenceX)
localY += contribution.weight * (deltas[componentY] - referenceY)
}
}
}
val worldX: Float
var worldZ: Float
if (parentWorld != null) {
parentWorld.apply(localX, localY, scratch, 0)
worldX = scratch[0]
worldZ = scratch[1]
} else {
worldX = localX
worldZ = localY
}
worldZ = -worldZ // the renderer's final Y negation
minX = min(minX, worldX)
minY = min(minY, worldZ)
maxX = max(maxX, worldX)
maxY = max(maxY, worldZ)
}
// A non-finite extent (a warp-extrapolated vertex divided by a degenerate cell, or corrupt control
// points) is NOT a usable bound: publish none, so the renderer keeps the safe full-viewport path
// rather than deriving a garbage scissor rect that would clip the whole subtree.
if (!minX.isFinite() || !minY.isFinite() || !maxX.isFinite() || !maxY.isFinite()) {
return null
}
return PosedAabb(minX, minY, maxX, maxY)
}
/** The union of two bounds. */
internal fun unionBounds(first: PosedAabb, second: PosedAabb): PosedAabb =
PosedAabb(
min(first.minX, second.minX),
min(first.minY, second.minY),
max(first.maxX, second.maxX),
max(first.maxY, second.maxY),
)
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,169 @@
package org.umamo.render
import org.umamo.format.art.LayerBounds
import org.umamo.runtime.model.AtlasPlacement
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Pins the collision regions the placement gizmo warns over: a tile's opaque mask marks exactly the
* texels at or above the threshold; a mesh mask covers a triangle's pixels plus one pixel of margin
* and leaves the corners of a thin diagonal mesh's box clear; a page occupancy finds painted pixels
* only where a sampled region actually covers them (not in a strand's empty corner, nor in a spot a
* mover is leaving); a sampled region hits a placed mask only on opaque texels or their extrusion
* band; and two tiles whose boxes overlap while their triangles and pixels stay apart never collide.
*/
class AtlasCollisionRegionsTest {
private fun raster(width: Int, height: Int, opaque: (Int, Int) -> Boolean): DecodedImage {
val rgba = ByteArray(width * height * 4)
for (y in 0 until height) {
for (x in 0 until width) {
if (opaque(x, y)) {
val offset = (y * width + x) * 4
rgba[offset] = 0x40
rgba[offset + 3] = 0xFF.toByte()
}
}
}
return DecodedImage(rgba, width, height)
}
private fun placement(x: Float, y: Float, rotationDegrees: Float = 0f): AtlasPlacement =
AtlasPlacement(0, x, y, 1f, 1f, rotationDegrees)
private fun triangle(x0: Float, y0: Float, x1: Float, y1: Float, x2: Float, y2: Float): FloatArray =
floatArrayOf(x0, y0, x1, y1, x2, y2)
/** A mesh covering the axis-aligned rectangle [left, right) by [top, bottom) with two triangles. */
private fun quadMesh(left: Float, top: Float, right: Float, bottom: Float): TileMeshMask =
assertNotNull(
TileMeshMask.of(
listOf(triangle(left, top, right, top, right, bottom), triangle(left, top, right, bottom, left, bottom)),
),
)
@Test
fun theOpaqueMaskMarksTexelsAtTheThreshold() {
val art = raster(6, 6) { x, y -> x == y }
val mask = TileOpaqueMask.of(art, LayerBounds(1, 1, 4, 4), alphaThreshold = 1)
assertTrue(mask.isOpaque(2, 2), "a diagonal texel inside the trim")
assertFalse(mask.isOpaque(2, 3), "an off-diagonal texel")
assertFalse(mask.isOpaque(0, 0), "outside the trim, even though the raster is opaque there")
}
@Test
fun theMeshMaskCoversATriangleAndOnePixelAround() {
// A right triangle with the right angle at (10, 10), legs of 8 along +x and +y.
val mask = assertNotNull(TileMeshMask.of(listOf(triangle(10f, 10f, 18f, 10f, 10f, 18f))))
assertTrue(mask.isCovered(11, 11), "inside")
assertTrue(mask.isCovered(9, 9), "the one-pixel margin around a corner")
assertFalse(mask.isCovered(17, 17), "the far corner of the bounding box, past the hypotenuse")
assertFalse(mask.isCovered(7, 7), "two pixels out is beyond the margin")
assertNull(TileMeshMask.of(emptyList()), "no triangles, no mask")
}
@Test
fun aThinDiagonalMeshLeavesItsBoxCornersClear() {
// A sliver along the diagonal of a 40x40 box.
val strand = assertNotNull(TileMeshMask.of(listOf(triangle(0f, 0f, 2f, 0f, 40f, 40f), triangle(0f, 0f, 40f, 40f, 38f, 40f))))
assertTrue(strand.isCovered(20, 20), "on the diagonal")
assertFalse(strand.isCovered(35, 5), "the box's top-right corner")
assertFalse(strand.isCovered(5, 35), "the box's bottom-left corner")
assertEquals(-1, strand.bounds.left, "the box carries the margin")
}
@Test
fun theOccupancyFindsPaintedPixelsInsideASampledRegionOnly() {
// A diagonal strand across a 32x32 page: painted only where x == y.
val page = raster(32, 32) { x, y -> x == y }
val occupancy = PageOccupancy.of(page, excluded = emptyList())
assertTrue(occupancy.isPainted(10, 10))
assertFalse(occupancy.isPainted(10, 11))
// A mesh in the strand's empty corner samples nothing, although the strand's box is the whole page.
val corner = SampledRegion(placement(20f, 2f), quadMesh(0f, 0f, 6f, 6f))
assertNull(occupancy.firstPaintedPixelIn(corner), "a region in the strand's empty corner is clear")
val across = SampledRegion(placement(12f, 12f), quadMesh(1f, 1f, 5f, 5f))
assertEquals(PixelRect(12, 12, 13, 13), occupancy.firstPaintedPixelIn(across), "a region across the strand hits its first painted pixel (the margin reaches one pixel out)")
}
@Test
fun anExcludedRectangleReadsAsEmpty() {
val page = raster(16, 16) { x, y -> x in 4 until 8 && y in 4 until 8 }
val occupancy = PageOccupancy.of(page, excluded = listOf(PixelRect(4, 4, 8, 8)))
assertFalse(occupancy.isPainted(5, 5), "the mover's old spot reads as empty")
assertTrue(occupancy.blockMayBePainted(0, 0), "the block bit ignores exclusions and the exact test decides")
assertNull(occupancy.firstPaintedPixelIn(SampledRegion(placement(3f, 3f), quadMesh(0f, 0f, 6f, 6f))))
}
@Test
fun aSampledRegionKeepsItsShapeUnderRotation() {
// A 10x4 mesh turned a quarter stands 4 wide and 10 tall (plus the margin), and the box's empty
// corners stay outside the region.
val region = SampledRegion(placement(20f, 20f, rotationDegrees = 90f), quadMesh(0f, 0f, 10f, 4f))
assertTrue(region.contains(18f, 25f), "inside the turned rectangle")
assertFalse(region.contains(13f, 25f), "beyond its short side and margin")
assertTrue(region.bounds.right - region.bounds.left in 5.9f..6.1f, "the bounds are 4 wide plus the margin")
assertTrue(region.bounds.bottom - region.bounds.top in 11.9f..12.1f, "and 10 tall plus the margin")
}
@Test
fun aSampledRegionHitsAPlacedMaskOnlyOnOpaqueTexelsOrTheirBand() {
// A painter whose only opaque texel is at (2, 2) of a 5x5 trim, placed at (10, 10): opaque
// page pixel (12, 12).
val painter = TileOpaqueMask.of(raster(5, 5) { x, y -> x == 2 && y == 2 }, LayerBounds(0, 0, 5, 5), alphaThreshold = 1)
val painterAt = placement(10f, 10f)
val point = quadMesh(0f, 0f, 1f, 1f)
// The mesh's margin reaches one pixel around (10, 10): pixels 9..11, all transparent.
val overTransparentCorner = SampledRegion(placement(10f, 10f), point)
assertFalse(sampledRegionHitsMask(overTransparentCorner, painterAt, painter, extrude = 2), "a transparent texel of the painter's rectangle is not paint")
val overTheTexel = SampledRegion(placement(12f, 12f), point)
assertTrue(sampledRegionHitsMask(overTheTexel, painterAt, painter, extrude = 0), "the opaque texel is paint")
// The band: a mesh two pixels past the trim's right edge, beside an opaque edge texel.
val bandRegion = SampledRegion(placement(16f, 12f), point)
assertFalse(sampledRegionHitsMask(bandRegion, painterAt, painter, extrude = 0), "without a band the edge is transparent")
val edgePainter = TileOpaqueMask.of(raster(5, 5) { x, _ -> x == 4 }, LayerBounds(0, 0, 5, 5), alphaThreshold = 1)
assertTrue(sampledRegionHitsMask(bandRegion, painterAt, edgePainter, extrude = 2), "an opaque edge texel's band counts as paint")
}
@Test
fun overlappingBoxesWithDisjointTrianglesAndPixelsNeverCollide() {
// The screenshot: a wide tile whose single triangular mesh overhangs its art and fills only the
// upper-left half of its box, and a strand whose sliver mesh hugs its diagonal pixels. Placed
// so the strand's pixels sit inside the wide mesh's BOX (its lower-right corner) while no
// triangle touches the other tile's pixels or its extrusion band.
val wideArt = raster(40, 20) { x, y -> x < 20 && y in 4 until 16 }
val wideMask = TileOpaqueMask.of(wideArt, LayerBounds(0, 4, 20, 12), alphaThreshold = 1)
val wideMesh = assertNotNull(TileMeshMask.of(listOf(triangle(0f, 2f, 24f, 2f, 0f, 18f))))
val wideAt = placement(0f, 0f)
val strandArt = raster(30, 30) { x, y -> x == y }
val strandMask = TileOpaqueMask.of(strandArt, LayerBounds(0, 0, 30, 30), alphaThreshold = 1)
val strandMesh = assertNotNull(TileMeshMask.of(listOf(triangle(0f, -1f, 30f, 29f, 0f, 1f), triangle(0f, 1f, 30f, 29f, 30f, 31f))))
// The strand's first pixels land at page (24, 9), (25, 10): inside the wide mesh's box (x to 25,
// y to 19), while the triangle's coverage at those rows ends near x = 16 - clear of the strand's
// two-pixel band even with the mesh's one-pixel margin - and past the wide art's own band.
val strandNear = placement(24f, 9f)
assertTrue(SampledRegion(wideAt, wideMesh).bounds.overlaps(placementFootprint(strandNear, strandMask.trim, reserve = null)), "the boxes do overlap")
assertFalse(sampledRegionHitsMask(SampledRegion(wideAt, wideMesh), strandNear, strandMask, extrude = 2), "the wide mesh's box holds the strand's pixels but its triangle does not reach them")
assertFalse(sampledRegionHitsMask(SampledRegion(strandNear, strandMesh), wideAt, wideMask, extrude = 2), "the strand's triangles never reach the wide tile's pixels or band")
// Slide the strand under the triangle and it collides.
val strandTouching = placement(4f, 6f)
assertTrue(sampledRegionHitsMask(SampledRegion(wideAt, wideMesh), strandTouching, strandMask, extrude = 2), "an overhanging triangle over the strand's pixels collides")
val strandFar = placement(30f, 0f)
assertFalse(sampledRegionHitsMask(SampledRegion(wideAt, wideMesh), strandFar, strandMask, extrude = 2), "far apart, nothing")
}
@Test
fun aMeshCoveringHalfItsTileIgnoresPaintUnderTheOtherHalf() {
// A bystander whose mesh covers only the left half of its 20x10 tile; a mover's opaque pixel
// under its right half is paint nobody samples.
val halfMesh = quadMesh(0f, 0f, 10f, 10f)
val bystanderAt = placement(0f, 0f)
val dot = TileOpaqueMask.of(raster(3, 3) { x, y -> x == 1 && y == 1 }, LayerBounds(0, 0, 3, 3), alphaThreshold = 1)
assertFalse(sampledRegionHitsMask(SampledRegion(bystanderAt, halfMesh), placement(15f, 4f), dot, extrude = 0), "paint under the unmeshed half")
assertTrue(sampledRegionHitsMask(SampledRegion(bystanderAt, halfMesh), placement(4f, 4f), dot, extrude = 0), "paint under the meshed half")
}
}
@@ -0,0 +1,70 @@
package org.umamo.render
import org.umamo.format.art.LayerBounds
import org.umamo.format.atlas.AtlasPackReserve
import org.umamo.runtime.model.AtlasPlacement
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertFalse
import kotlin.test.assertTrue
/**
* Pins the placement footprint the gizmo warns over: an upright placement's footprint is its trim at
* its position, a mesh reserve widens it, a turned placement's footprint is the turned rectangle's
* bounding box, and the overlap / off-page tests read those edges the way the composer will paint
* them.
*/
class AtlasPlacementDragTest {
private val trim = LayerBounds(2, 3, 8, 6)
private fun placement(x: Float, y: Float, rotationDegrees: Float = 0f, scale: Float = 1f): AtlasPlacement =
AtlasPlacement(0, x, y, scale, scale, rotationDegrees)
private fun assertClose(expected: Float, actual: Float, message: String) {
assertTrue(abs(expected - actual) < 1e-3f, "$message: expected $expected, was $actual")
}
private fun assertFootprint(expected: PlacementFootprint, actual: PlacementFootprint) {
assertClose(expected.left, actual.left, "left")
assertClose(expected.top, actual.top, "top")
assertClose(expected.right, actual.right, "right")
assertClose(expected.bottom, actual.bottom, "bottom")
}
@Test
fun anUprightFootprintIsTheTrimAtThePosition() {
assertFootprint(PlacementFootprint(12f, 23f, 20f, 29f), placementFootprint(placement(10f, 20f), trim, reserve = null))
}
@Test
fun aMeshReserveWidensTheFootprint() {
val reserve = AtlasPackReserve(left = -1, top = 0, right = 12, bottom = 5)
assertFootprint(PlacementFootprint(9f, 20f, 22f, 29f), placementFootprint(placement(10f, 20f), trim, reserve))
}
@Test
fun aScaledFootprintScalesAboutTheTileOrigin() {
assertFootprint(PlacementFootprint(11f, 21.5f, 15f, 24.5f), placementFootprint(placement(10f, 20f, scale = 0.5f), trim, reserve = null))
}
@Test
fun aQuarterTurnedFootprintIsTheTurnedRectanglesBounds() {
// A 90 degree placement maps (x, y) to (-y, x) about the tile origin: the 8x6 trim becomes 6 wide by 8 tall.
val footprint = placementFootprint(placement(10f, 20f, rotationDegrees = 90f), trim, reserve = null)
assertClose(6f, footprint.right - footprint.left, "turned width")
assertClose(8f, footprint.bottom - footprint.top, "turned height")
assertClose(10f - 9f, footprint.left, "the trim's bottom edge (y = 9) turns to x = -9")
assertClose(20f + 2f, footprint.top, "the trim's left edge (x = 2) turns to y = 2")
}
@Test
fun overlapAndPageTestsReadTheEdges() {
val one = PlacementFootprint(0f, 0f, 10f, 10f)
assertTrue(one.overlaps(PlacementFootprint(9f, 9f, 20f, 20f)), "shared area overlaps")
assertFalse(one.overlaps(PlacementFootprint(10f, 0f, 20f, 10f)), "a touching edge is not an overlap")
assertTrue(one.expanded(2f).overlaps(PlacementFootprint(11f, 0f, 20f, 10f)), "the gutter margin reaches a neighbor one pixel away")
assertFalse(one.exceeds(10, 10), "a footprint filling the page exactly stays on it")
assertTrue(one.expanded(1f).exceeds(10, 10), "growing past the edge spills")
assertTrue(PlacementFootprint(-0.5f, 0f, 5f, 5f).exceeds(64, 64), "a fractional overhang spills")
}
}
@@ -0,0 +1,389 @@
package org.umamo.render
import org.umamo.format.atlas.AtlasPackFixed
import org.umamo.format.atlas.AtlasPackItem
import org.umamo.format.atlas.AtlasPackOptions
import org.umamo.format.atlas.AtlasPackPlacement
import org.umamo.format.atlas.composeAtlasPages
import org.umamo.format.atlas.packAtlas
import org.umamo.runtime.model.AtlasPage
import org.umamo.runtime.model.AtlasPlacement
import org.umamo.runtime.model.AtlasTile
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.PuppetAtlas
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.placementAffine
import kotlin.test.Test
import kotlin.test.assertContentEquals
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Pins the generated-page derivation against the packer itself: packing a tile set and deriving the
* pages back from the lowered placements must produce byte-identical pixels and the same page
* numbering. This is the gate on the trim/extrude coupling - the derivation re-runs the packer's
* trim analysis under the same policy, and any drift between the two shows up here as a byte diff.
* Beyond the packer's own placements, a hand-authored one (moved, scaled, rotated, off the pixel
* grid) derives through the affine composer instead of being refused - and one the packer KEPT as a
* fixed tile derives byte-identically beside the tiles it packed around it.
*/
class DerivedAtlasTexturesTest {
private val tileIds = listOf(AtlasTileId("t0"), AtlasTileId("t1"), AtlasTileId("t2"))
/**
* A raster with a transparent margin around a filled core, so the pack genuinely trims.
*
* @param Int width The raster width in pixels.
* @param Int height The raster height in pixels.
* @param Int margin The transparent border width on every side.
* @param Int red The core's red byte.
* @return ByteArray RGBA8888 pixels.
*/
private fun tileRaster(width: Int, height: Int, margin: Int, red: Int): ByteArray {
val rgba = ByteArray(width * height * 4)
for (rowIndex in margin until height - margin) {
for (columnIndex in margin until width - margin) {
val offset = (rowIndex * width + columnIndex) * 4
rgba[offset] = red.toByte()
rgba[offset + 1] = (rowIndex * 16 + columnIndex).toByte()
rgba[offset + 2] = 0x40
rgba[offset + 3] = 0xFF.toByte()
}
}
return rgba
}
private class Fixture(
val model: PuppetModel,
val store: SourceArtRasters,
val packedPages: List<DecodedImage>,
val rasters: List<DecodedImage>,
)
/**
* Three tiles packed by the packer, lowered onto a model, and a store serving their pixels.
*
* @param List extraTiles Tiles appended to the atlas AFTER the pack, with the raster the store serves for each.
* @return Fixture The packed model, its store, the packer's pages, and the three tile rasters.
*/
private fun packedFixture(extraTiles: List<Pair<AtlasTile, DecodedImage>> = emptyList()): Fixture {
val rasters =
listOf(
DecodedImage(tileRaster(12, 10, 2, 0x10), 12, 10),
DecodedImage(tileRaster(8, 16, 1, 0x20), 8, 16),
DecodedImage(tileRaster(10, 10, 0, 0x30), 10, 10),
)
val items =
tileIds.mapIndexed { tileIndex, tileId ->
AtlasPackItem(tileId.raw, rasters[tileIndex].width, rasters[tileIndex].height, rasters[tileIndex].rgba)
}
val result = packAtlas(items, AtlasPackOptions(maxPageSize = 64))
assertEquals(tileIds.size, result.placements.size, "every fixture tile packs")
val placementByKey = result.placements.associateBy { placement -> placement.key }
val tiles =
tileIds.mapIndexed { tileIndex, tileId ->
AtlasTile(
tileId,
tileId.raw,
rasters[tileIndex].width,
rasters[tileIndex].height,
atlasPlacementFromPack(placementByKey.getValue(tileId.raw)),
)
} + extraTiles.map { (tile, _) -> tile }
val drawables =
tileIds.mapIndexed { tileIndex, tileId ->
Drawable(
id = DrawableId("d$tileIndex"),
name = "d$tileIndex",
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = null,
geometryGrid = null,
atlasTileId = tileId,
)
}
val model =
PuppetModel(
parameters = emptyList(),
parts = emptyList(),
deformers = emptyList(),
drawables = drawables,
rootChildren = emptyList(),
rootPartId = null,
canvasWidth = 100f,
canvasHeight = 100f,
worldOriginX = 50f,
worldOriginZ = 50f,
atlas =
PuppetAtlas(
pages = result.pages.map { page -> AtlasPage(page.width, page.height) },
tiles = tiles,
),
)
val pngByTile = HashMap<AtlasTileId, ByteArray>()
for ((tileIndex, tileId) in tileIds.withIndex()) {
pngByTile[tileId] = encodeAtlasPng(rasters[tileIndex])
}
for ((tile, raster) in extraTiles) {
pngByTile[tile.id] = encodeAtlasPng(raster)
}
val store = SourceArtRasters.fromPng { tileId -> pngByTile[tileId] }
return Fixture(model, store, result.pages.map { page -> DecodedImage(page.rgba, page.width, page.height) }, rasters)
}
private fun alphaAt(page: DecodedImage, x: Int, y: Int): Int = page.rgba[(y * page.width + x) * 4 + 3].toInt() and 0xFF
private fun pixelBytes(image: DecodedImage, x: Int, y: Int): ByteArray {
val offset = (y * image.width + x) * 4
return image.rgba.copyOfRange(offset, offset + 4)
}
private fun PuppetModel.withTilePlacement(tileIndex: Int, placement: AtlasPlacement): PuppetModel =
copy(atlas = atlas.copy(tiles = atlas.tiles.mapIndexed { index, tile -> if (index == tileIndex) tile.copy(placement = placement) else tile }))
@Test
fun derivedPagesAreByteIdenticalToThePackersAndShareItsNumbering() {
val fixture = packedFixture()
val model = fixture.model
val derived = assertNotNull(deriveAtlasTextures(model, fixture.store, premultipliedAlpha = true))
assertEquals(fixture.packedPages.size, derived.atlases.size, "one derived page per packed page")
for (pageIndex in fixture.packedPages.indices) {
assertEquals(fixture.packedPages[pageIndex].width, derived.atlases[pageIndex].width)
assertEquals(fixture.packedPages[pageIndex].height, derived.atlases[pageIndex].height)
assertContentEquals(
fixture.packedPages[pageIndex].rgba,
derived.atlases[pageIndex].rgba,
"page $pageIndex pixels re-derive byte-identically",
)
}
assertTrue(derived.premultipliedAlpha, "the convention flag passes through")
for ((tileIndex, tileId) in tileIds.withIndex()) {
val placement = assertNotNull(model.atlas.tiles[tileIndex].placement)
assertEquals(
placement.pageIndex,
derived.atlasIndexByDrawableId["d$tileIndex"],
"drawable d$tileIndex maps to its tile '$${tileId.raw}' page under the MODEL's numbering",
)
}
}
@Test
fun aScaledPlacementDerivesThroughTheAffinePath() {
val fixture = packedFixture()
val original = assertNotNull(fixture.model.atlas.tiles[0].placement)
val scaled = fixture.model.withTilePlacement(0, original.copy(scaleX = 0.5f, scaleY = 0.5f))
val derived = assertNotNull(deriveAtlasTextures(scaled, fixture.store, false), "a scaled placement resamples rather than refusing")
val page = derived.atlases[original.pageIndex]
// Tile 0's opaque core is its 8x6 trim at (2, 2); halved about the tile origin it covers
// [origin + 1, origin + 5) by [origin + 1, origin + 4), and its old far corner is vacated.
val originX = original.positionX.toInt()
val originY = original.positionY.toInt()
assertEquals(255, alphaAt(page, originX + 2, originY + 2), "inside the halved footprint")
assertEquals(0, alphaAt(page, originX + 8, originY + 6), "the unscaled footprint's far corner is empty now")
assertFalse(page.rgba.contentEquals(fixture.packedPages[original.pageIndex].rgba), "the page changed")
}
@Test
fun aMovedPlacementComposesTheTileAtItsNewSpotAndVacatesTheOld() {
val fixture = packedFixture()
val original = assertNotNull(fixture.model.atlas.tiles[0].placement)
val packedPage = fixture.packedPages[original.pageIndex]
// The trim origin on the page, and a move of three pixels toward whichever side has room.
val trimPageX = original.positionX.toInt() + 2
val trimPageY = original.positionY.toInt() + 2
val deltaX = if (trimPageX + 8 + 3 + 2 <= packedPage.width) 3 else -3
val deltaY = if (trimPageY + 6 + 2 + 2 <= packedPage.height) 2 else -2
val moved = fixture.model.withTilePlacement(0, original.copy(positionX = original.positionX + deltaX, positionY = original.positionY + deltaY))
val derived = assertNotNull(deriveAtlasTextures(moved, fixture.store, false))
val page = derived.atlases[original.pageIndex]
assertContentEquals(
pixelBytes(fixture.rasters[0], 3, 3),
pixelBytes(page, trimPageX + deltaX + 1, trimPageY + deltaY + 1),
"the tile's pixels sit at the new spot verbatim",
)
val vacatedX = if (deltaX > 0) trimPageX else trimPageX + 7
assertEquals(255, alphaAt(packedPage, vacatedX, trimPageY), "the column was the tile's before the move")
assertEquals(0, alphaAt(page, vacatedX, trimPageY), "the column the tile left behind is empty (beyond the extrusion band)")
}
@Test
fun aRotatedFractionalPlacementDerives() {
val fixture = packedFixture()
val original = assertNotNull(fixture.model.atlas.tiles[0].placement)
val turned = original.copy(positionX = original.positionX + 0.5f, rotationDegrees = 30f)
val rotated = fixture.model.withTilePlacement(0, turned)
val derived = assertNotNull(deriveAtlasTextures(rotated, fixture.store, false), "rotation and a fractional position resample rather than refuse")
val page = derived.atlases[original.pageIndex]
val trim = assertNotNull(derivedTileTrim(fixture.rasters[0], rotated.atlas.composition.alphaThreshold))
val footprint = placementFootprint(turned, trim, reserve = null)
val centerX = ((footprint.left + footprint.right) / 2f).toInt().coerceIn(0, page.width - 1)
val centerY = ((footprint.top + footprint.bottom) / 2f).toInt().coerceIn(0, page.height - 1)
assertTrue(alphaAt(page, centerX, centerY) > 0, "the turned tile's center is painted")
}
@Test
fun aTurnedPackPlacementLowersAndDerivesByteIdenticallyToThePackersPage() {
val fixture = packedFixture()
val pageSide = 64
// Tile 1 (8x16, trimmed to 6x14 at (1, 1)) placed turned: its footprint is 14 wide by 6 tall.
val packPlacements =
listOf(
AtlasPackPlacement(tileIds[0].raw, 0, pageX = 2, pageY = 2, trimLeft = 2, trimTop = 2, trimWidth = 8, trimHeight = 6, quarterTurns = 0),
AtlasPackPlacement(tileIds[1].raw, 0, pageX = 20, pageY = 2, trimLeft = 1, trimTop = 1, trimWidth = 6, trimHeight = 14, quarterTurns = 1),
AtlasPackPlacement(tileIds[2].raw, 0, pageX = 2, pageY = 20, trimLeft = 0, trimTop = 0, trimWidth = 10, trimHeight = 10, quarterTurns = 0),
)
val items =
tileIds.mapIndexed { tileIndex, tileId ->
AtlasPackItem(tileId.raw, fixture.rasters[tileIndex].width, fixture.rasters[tileIndex].height, fixture.rasters[tileIndex].rgba)
}
val packedPage = composeAtlasPages(intArrayOf(pageSide), intArrayOf(pageSide), items, packPlacements, extrude = 2).single()
val tiles = fixture.model.atlas.tiles.mapIndexed { tileIndex, tile -> tile.copy(placement = atlasPlacementFromPack(packPlacements[tileIndex])) }
val model = fixture.model.copy(atlas = PuppetAtlas(pages = listOf(AtlasPage(pageSide, pageSide)), tiles = tiles))
val turned = assertNotNull(model.atlas.tiles[1].placement)
assertEquals(-90f, turned.rotationDegrees, "a packer quarter turn lowers as a -90 degree placement rotation")
val derived = assertNotNull(deriveAtlasTextures(model, fixture.store, false))
val page = derived.atlases[0]
// The turn sends the trim origin (1, 1) to the packed rect's bottom-left (20, 2 + 6 - 1) and the
// trim's far corner (6, 14) to its top-right (20 + 13, 2).
assertContentEquals(pixelBytes(fixture.rasters[1], 1, 1), pixelBytes(page, 20, 7), "the trim origin lands at the packed rect's bottom-left")
assertContentEquals(pixelBytes(fixture.rasters[1], 6, 14), pixelBytes(page, 33, 2), "the trim's far corner lands at the packed rect's top-right")
assertContentEquals(packedPage.rgba, page.rgba, "a turned pack derives through the packer's own blit, byte for byte")
}
@Test
fun aPinnedTileDerivesByteIdenticallyToThePackersPage() {
val fixture = packedFixture()
// Tile 1 kept at a hand placement - turned 30 degrees, reduced to 0.75, at (30, 30) - while the
// other two pack around it.
val kept = AtlasPlacement(pageIndex = 0, positionX = 30f, positionY = 30f, scaleX = 0.75f, scaleY = 0.75f, rotationDegrees = 30f)
val items =
tileIds.mapIndexed { tileIndex, tileId ->
val raster = fixture.rasters[tileIndex]
AtlasPackItem(
tileId.raw,
raster.width,
raster.height,
raster.rgba,
fixed = if (tileIndex == 1) AtlasPackFixed(kept.pageIndex, placementAffine(kept)) else null,
)
}
val options = AtlasPackOptions(maxPageSize = 64)
val result = packAtlas(items, options)
assertEquals(tileIds[1].raw, result.fixed.single().key, "the pinned tile is kept, not packed")
assertEquals(2, result.placements.size, "the other two pack")
val placementByKey = result.placements.associateBy { placement -> placement.key }
val tiles =
fixture.model.atlas.tiles.mapIndexed { tileIndex, tile ->
if (tileIndex == 1) {
tile.copy(placement = kept, pinned = true)
} else {
tile.copy(placement = atlasPlacementFromPack(placementByKey.getValue(tile.id.raw)))
}
}
val model =
fixture.model.copy(
atlas =
PuppetAtlas(
pages = result.pages.map { page -> AtlasPage(page.width, page.height) },
tiles = tiles,
composition = atlasCompositionOf(options),
),
)
val derived = assertNotNull(deriveAtlasTextures(model, fixture.store, false))
assertEquals(result.pages.size, derived.atlases.size)
for (pageIndex in result.pages.indices) {
assertContentEquals(result.pages[pageIndex].rgba, derived.atlases[pageIndex].rgba, "page $pageIndex derives byte-identically, pinned tile included")
}
val trim = assertNotNull(derivedTileTrim(fixture.rasters[1], model.atlas.composition.alphaThreshold))
val footprint = placementFootprint(kept, trim, reserve = null)
val centerX = ((footprint.left + footprint.right) / 2f).toInt()
val centerY = ((footprint.top + footprint.bottom) / 2f).toInt()
assertEquals(255, alphaAt(derived.atlases[0], centerX, centerY), "the kept tile is painted where its placement says")
}
@Test
fun theDerivationTrimsAndExtrudesUnderTheAtlasOwnComposition() {
// A 10x10 raster whose one-pixel border is half-transparent: inside the trim at threshold 1,
// trimmed away at threshold 128.
val side = 10
val bordered = ByteArray(side * side * 4)
for (rowIndex in 0 until side) {
for (columnIndex in 0 until side) {
val onBorder = rowIndex == 0 || columnIndex == 0 || rowIndex == side - 1 || columnIndex == side - 1
val offset = (rowIndex * side + columnIndex) * 4
bordered[offset] = 0x50
bordered[offset + 1] = (rowIndex * 16 + columnIndex).toByte()
bordered[offset + 2] = 0x40
bordered[offset + 3] = if (onBorder) 0x60 else 0xFF.toByte()
}
}
val tileId = tileIds[0]
val options = AtlasPackOptions(maxPageSize = 32, alphaThreshold = 128, extrude = 0)
val result = packAtlas(listOf(AtlasPackItem(tileId.raw, side, side, bordered)), options)
val packPlacement = result.placements.single()
assertEquals(side - 2, packPlacement.trimWidth, "the border is trimmed away at threshold 128")
val fixture = packedFixture()
val store = SourceArtRasters.fromPng { id -> if (id == tileId) encodeAtlasPng(DecodedImage(bordered, side, side)) else null }
val tiles = listOf(AtlasTile(tileId, tileId.raw, side, side, atlasPlacementFromPack(packPlacement)))
val pages = result.pages.map { page -> AtlasPage(page.width, page.height) }
val underPolicy = fixture.model.copy(atlas = PuppetAtlas(pages, tiles, composition = atlasCompositionOf(options)))
val underDefault = fixture.model.copy(atlas = PuppetAtlas(pages, tiles))
val derived = assertNotNull(deriveAtlasTextures(underPolicy, store, false))
assertContentEquals(result.pages.single().rgba, derived.atlases.single().rgba, "the stored composition reproduces the pack's page")
val defaulted = assertNotNull(deriveAtlasTextures(underDefault, store, false))
assertFalse(
defaulted.atlases.single().rgba.contentEquals(result.pages.single().rgba),
"the default policy draws the border and an extrusion band, so it is not the pack's page",
)
}
@Test
fun aPlacedTileWithNothingOpaqueIsSkippedNotRefused() {
val emptyTile = AtlasTile(AtlasTileId("empty"), "empty", 4, 4, AtlasPlacement(0, 0f, 0f, 1f, 1f, 0f))
val fixture = packedFixture(extraTiles = listOf(emptyTile to DecodedImage(ByteArray(4 * 4 * 4), 4, 4)))
val derived = assertNotNull(deriveAtlasTextures(fixture.model, fixture.store, false), "an empty placed tile draws nothing")
for (pageIndex in fixture.packedPages.indices) {
assertContentEquals(fixture.packedPages[pageIndex].rgba, derived.atlases[pageIndex].rgba, "page $pageIndex is untouched by the empty tile")
}
}
@Test
fun artThatWillNotDecodeIsNotDerivable() {
val fixture = packedFixture()
val brokenStore = SourceArtRasters.fromPng { ByteArray(4) }
assertNull(deriveAtlasTextures(fixture.model, brokenStore, false), "undecodable art cannot compose a page")
assertNull(planAtlasDerivation(fixture.model, brokenStore), "the plan refuses before any pixel is composed")
}
@Test
fun aPlacementNamingAMissingPageIsNotDerivable() {
val fixture = packedFixture()
val original = assertNotNull(fixture.model.atlas.tiles[0].placement)
val stray = fixture.model.withTilePlacement(0, original.copy(pageIndex = fixture.model.atlas.pages.size))
assertNull(planAtlasDerivation(stray, fixture.store), "a page the atlas lacks is a document fault, not a placement to resample")
}
}
@@ -0,0 +1,208 @@
package org.umamo.render
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import org.umamo.runtime.model.AtlasPage
import org.umamo.runtime.model.AtlasPlacement
import org.umamo.runtime.model.AtlasTile
import org.umamo.runtime.model.AtlasTileId
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.OrgChild
import org.umamo.runtime.model.PuppetAtlas
import org.umamo.runtime.model.PuppetModel
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Pins which drawables map onto their source artwork and which fall back to the atlas, and that
* working the mapping out costs no decoding.
*
* The mode is best-effort per drawable rather than a clean flip, so the interesting cases are the ways
* a drawable can fail to map: no binding, or a placement that will not invert. Each keeps the drawable
* on the atlas and counts it, because a puppet drawn mostly from its atlas must not look like one drawn
* from its artwork. Art that will not DECODE is deliberately not one of those cases here - the plan
* carries no pixels, so that failure surfaces later, from the batch that tried.
*/
class LayerDrawPlanTest {
private fun meshedDrawable(rawId: String, tileId: String? = null): Drawable =
Drawable(
id = DrawableId(rawId),
name = rawId,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f), floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f), intArrayOf(0, 1, 2)),
geometryGrid = null,
atlasTileId = tileId?.let { raw -> AtlasTileId(raw) },
)
private fun bareDrawable(rawId: String): Drawable =
Drawable(
id = DrawableId(rawId),
name = rawId,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = null,
geometryGrid = null,
)
private fun modelOf(atlas: PuppetAtlas = PuppetAtlas.Empty, vararg drawables: Drawable): PuppetModel =
PuppetModel(
parameters = emptyList(),
parts = emptyList(),
deformers = emptyList(),
drawables = drawables.toList(),
rootChildren = drawables.map { drawable -> OrgChild.Drawable(drawable.id) },
rootPartId = null,
atlas = atlas,
)
private fun onePixelPng(): ByteArray = PngCodec.write(RasterImage(1, 1, byteArrayOf(1, 2, 3, 4)))
/** A tile whose art was never packed, so its drawables' uvs already address it. */
private fun unpackedTile(rawId: String, width: Int = 8, height: Int = 8): AtlasTile =
AtlasTile(AtlasTileId(rawId), name = "Art", width = width, height = height)
/** A drawable with usable artwork gets a draw; a layer is costed once, however many share it. */
@Test
fun resolvedDrawablesShareOneLayerCost() {
val model =
modelOf(
PuppetAtlas(tiles = listOf(unpackedTile("layer0"))),
meshedDrawable("a", "layer0"),
meshedDrawable("b", "layer0"),
)
val plan = buildLayerDrawPlan(model)
assertEquals(setOf("a", "b"), plan.drawsByDrawableId.keys, "both drawables map")
assertEquals(1, plan.layerByteCostByKey.size, "shared art is costed once, not once per drawable")
assertEquals(8L * 8L * 4L, plan.layerByteCostByKey.getValue("layer0"), "costed from the inventory size, before any decode")
assertEquals(0, plan.unresolvedDrawableCount, "nothing fell back")
}
/** A drawable with no binding falls back to the atlas and is counted, rather than vanishing. */
@Test
fun unboundDrawableFallsBackAndIsCounted() {
val model =
modelOf(
PuppetAtlas(tiles = listOf(unpackedTile("layer0"))),
meshedDrawable("a", "layer0"),
meshedDrawable("unbound"),
)
val plan = buildLayerDrawPlan(model)
assertEquals(setOf("a"), plan.drawsByDrawableId.keys, "only the bound drawable maps")
assertEquals(1, plan.unresolvedDrawableCount, "the unbound one is counted, not hidden")
}
/** A placement that will not invert leaves its drawable on the atlas. */
@Test
fun degeneratePlacementFallsBack() {
val degenerate =
unpackedTile("layer0")
.copy(placement = AtlasPlacement(0, 0f, 0f, scaleX = 0f, scaleY = 1f, rotationDegrees = 0f))
val model =
modelOf(
PuppetAtlas(pages = listOf(AtlasPage(64, 64)), tiles = listOf(degenerate)),
meshedDrawable("a", "layer0"),
)
val plan = buildLayerDrawPlan(model)
assertTrue(plan.drawsByDrawableId.isEmpty(), "a mapping that cannot be formed draws nothing from artwork")
assertEquals(1, plan.unresolvedDrawableCount, "and the drawable is counted")
}
/**
* Building the mapping decodes nothing at all.
*
* The whole point of the split: a document referencing hundreds of layers must be able to work out
* what maps where without paying for the pixels, or switching display mode would cost gigabytes
* before anything appeared.
*/
@Test
fun buildingThePlanDecodesNothing() {
var decodes = 0
SourceArtRasters.fromPng { _ ->
decodes++
onePixelPng()
}
val plan =
buildLayerDrawPlan(
modelOf(PuppetAtlas(tiles = listOf(unpackedTile("layer0"))), meshedDrawable("a", "layer0")),
)
assertEquals(0, decodes, "the mapping is worked out from the inventory, never from the pixels")
assertNotNull(plan.drawsByDrawableId["a"], "and the drawable still maps")
}
/**
* Art that will not decode is attributed to every drawable over it.
*
* The plan cannot know this - it decodes nothing - so the producer discovers it from a delivery and
* asks the plan who was affected. That is what keeps the reported gap counting drawables with no
* usable artwork, rather than layers.
*/
@Test
fun undecodableLayersMapBackToTheirDrawables() {
val model =
modelOf(
PuppetAtlas(tiles = listOf(unpackedTile("layer0"), unpackedTile("layer1"))),
meshedDrawable("a", "layer0"),
meshedDrawable("b", "layer0"),
meshedDrawable("c", "layer1"),
)
val plan = buildLayerDrawPlan(model)
assertEquals(setOf("a", "b"), plan.drawableIdsUsing(setOf("layer0")), "both users of the failed art are named")
assertEquals(emptySet(), plan.drawableIdsUsing(emptySet()), "and nothing is named when nothing failed")
}
/** Unmeshed drawables are not counted: they draw nothing either way. */
@Test
fun unmeshedDrawablesAreNotCounted() {
val plan = buildLayerDrawPlan(modelOf(PuppetAtlas(tiles = listOf(unpackedTile("layer0"))), bareDrawable("c")))
assertEquals(0, plan.unresolvedDrawableCount, "a drawable with no mesh is not a fallback")
}
/** An empty atlas means the packed pages, with no work done at all. */
@Test
fun anEmptyAtlasYieldsThePackedPages() {
val plan = buildLayerDrawPlan(modelOf(PuppetAtlas.Empty, meshedDrawable("a")))
assertTrue(plan.isEmpty, "no artwork means displaying from the atlas")
}
/**
* A session-created duplicate finds its art natively.
*
* The tile is a field on the drawable, so a copy carries it like every other field - where the atlas
* page still resolves through textureSourceId, because THAT map is keyed by the source format's own
* drawable ids and a fresh duplicate has no entry in it.
*/
@Test
fun aDuplicateCarriesItsOwnTileBinding() {
val model =
modelOf(
PuppetAtlas(tiles = listOf(unpackedTile("layer0"))),
meshedDrawable("a", "layer0"),
meshedDrawable("a copy", "layer0").copy(textureSourceId = DrawableId("a")),
)
val plan = buildLayerDrawPlan(model)
assertNotNull(plan.drawsByDrawableId["a copy"], "the duplicate resolves its own tile")
assertEquals(0, plan.unresolvedDrawableCount, "so it is not a fallback")
}
/** The uncached decode shares nothing with the caching one, so it is safe off the owning thread. */
@Test
fun uncachedDecodeSharesNothing() {
val tileId = AtlasTileId("layer0")
val store = SourceArtRasters.fromPng { requested -> if (requested == tileId) onePixelPng() else null }
val cached = store.rasterFor(tileId)
val fresh = store.decodeRaster(tileId)
assertNotNull(cached, "the caching path decodes")
assertNotNull(fresh, "the uncached path decodes")
assertTrue(cached !== fresh, "the uncached path owns its result rather than sharing the cache's")
assertNull(store.decodeRaster(AtlasTileId("missing")), "an unknown tile decodes to nothing")
}
}
@@ -0,0 +1,182 @@
package org.umamo.render
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
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.PuppetModel
import org.umamo.runtime.model.RotationPivotForm
import org.umamo.runtime.model.WarpLatticeForm
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
/**
* The canvas-space conversion's two halves agree about WHICH POSE a hidden drawable is mapped at.
*
* A drawable whose keyform axis does not bracket its parameter's default - the toggle-part authoring
* pattern - is absent from the raw default pose, so [restMeshesToCanvasSpace] maps it forward through a
* second pose with that parameter clamped into its axis's key range. The export's inverse has to use
* the same clamped pose, or it undoes a transform that was never applied.
*
* With the two halves disagreeing, this drawable's chain does not resolve at the raw default at all and
* the seam returns null - which the export turns into a notice and writes the mesh as authored, in the
* wrong space. The rotation parent is what makes the poses distinguishable: it is keyed so its scale
* differs across the toggle's range, so agreeing on the pose is load-bearing rather than incidental.
*/
class Moc3HiddenDrawableSpaceTest {
private val toggle = ParameterId("Toggle")
private val drawableId = DrawableId("M")
private val deformerId = DeformerId("R")
/** The parent-space rest positions the drawable is authored with. */
private val parentLocal = floatArrayOf(1f, 2f, 3f, 4f, 5f, 6f)
/**
* A rotation deformer whose scale differs across the toggle's key range.
*
* Keys at 0.5 and 1.0 over a parameter defaulting to 0: the raw default sits BELOW the span, which
* is what hides the child, and the clamped pose lands on 0.5.
*
* @return Deformer.Rotation The parent.
*/
private fun togglingRotation(): Deformer.Rotation =
Deformer.Rotation(
deformerId,
"R",
null,
null,
0f,
KeyformGrid(
listOf(KeyformAxis(toggle, floatArrayOf(0.5f, 1f))),
listOf(
KeyformCell(intArrayOf(0), RotationPivotForm(5f, 5f, 90f, 2f)),
KeyformCell(intArrayOf(1), RotationPivotForm(5f, 5f, 90f, 4f)),
),
),
)
/**
* A model whose only drawable is hidden at the raw default pose.
*
* @return PuppetModel The model.
*/
private fun hiddenAtDefaultModel(): PuppetModel {
val drawable =
Drawable(
id = drawableId,
name = "M",
parentDeformerId = deformerId,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(parentLocal, FloatArray(parentLocal.size), intArrayOf(0, 1, 2)),
geometryGrid =
KeyformGrid(
listOf(KeyformAxis(toggle, floatArrayOf(0.5f, 1f))),
listOf(
KeyformCell(intArrayOf(0), MeshDeltaForm(FloatArray(parentLocal.size))),
KeyformCell(intArrayOf(1), MeshDeltaForm(FloatArray(parentLocal.size))),
),
),
)
return PuppetModel(
parameters = listOf(Parameter(toggle, "Toggle", min = 0f, max = 1f, default = 0f)),
parts = emptyList(),
deformers = listOf(togglingRotation()),
drawables = listOf(drawable),
rootChildren = listOf(OrgChild.Drawable(drawableId)),
rootPartId = null,
)
}
@Test
fun aHiddenDrawableSurvivesTheCanvasSpaceRoundTrip() {
val model = hiddenAtDefaultModel()
// Forward: the import's pass, which rescues this drawable through the clamped pose.
val canvasSpace = restMeshesToCanvasSpace(model)
val canvasMesh = assertNotNull(canvasSpace.drawables.single().mesh)
assertTrue(
canvasMesh.positions.toList() != parentLocal.toList(),
"the forward pass must actually have moved the mesh, or this proves nothing",
)
// Back: the export's seam. It has to pick the same pose the forward pass used.
val recovered = assertNotNull(canvasToParentSpaceFor(canvasSpace)(drawableId, canvasMesh.positions))
for (index in parentLocal.indices) {
val drift = abs(recovered[index] - parentLocal[index])
assertTrue(
drift < 1e-2f,
"coordinate $index came back as ${recovered[index]}, authored ${parentLocal[index]} - " +
"the inverse used a different pose than the forward pass",
)
}
}
/**
* UMA / CMO3 unkeyed warp children already store lattice UV in the rest mesh. Treating that as
* canvas and inverting through the warp is the MouthCircle corruption: UV (~0..1) becomes garbage
* outside the lattice and the mesh flies off when the parent opens.
*/
@Test
fun anAlreadyParentLocalWarpChildIsNotDoubleTransformed() {
val warpId = DeformerId("W")
val pose = ParameterId("Pose")
// Canvas-space lattice; child rest is parent-local UV - the UMA MouthCircle convention.
val lattice = floatArrayOf(100f, 200f, 300f, 200f, 100f, 400f, 300f, 400f)
val warp =
Deformer.Warp(
warpId,
"W",
null,
null,
1,
1,
true,
KeyformGrid(
listOf(KeyformAxis(pose, floatArrayOf(0f))),
listOf(KeyformCell(intArrayOf(0), WarpLatticeForm(lattice))),
),
)
val uvRest = floatArrayOf(0.25f, 0.25f, 0.75f, 0.25f, 0.75f, 0.75f, 0.25f, 0.75f)
val drawable =
Drawable(
id = drawableId,
name = "MouthCircle",
parentDeformerId = warpId,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(uvRest, FloatArray(uvRest.size), intArrayOf(0, 1, 2)),
geometryGrid = null,
)
val model =
PuppetModel(
parameters = listOf(Parameter(pose, "Pose", min = 0f, max = 1f, default = 0f)),
parts = emptyList(),
deformers = listOf(warp),
drawables = listOf(drawable),
rootChildren = listOf(OrgChild.Drawable(drawableId)),
rootPartId = null,
)
val recovered = assertNotNull(canvasToParentSpaceFor(model)(drawableId, uvRest))
for (index in uvRest.indices) {
val drift = abs(recovered[index] - uvRest[index])
assertTrue(
drift < 1e-4f,
"coordinate $index was rewritten from parent-local ${uvRest[index]} to ${recovered[index]} - " +
"the seam double-transformed an already-local rest mesh",
)
}
}
}
@@ -0,0 +1,132 @@
package org.umamo.render
import org.umamo.runtime.keyform.fanOutMesh
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.KeyformAxis
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PuppetModel
import kotlin.test.Test
import kotlin.test.assertEquals
/**
* Unit tests for [restMeshesToCanvasSpace] on a tiny synthetic model. The rebase rewrites ONLY the
* geometry (base positions and keyform/blend-shape deltas); every non-positional keyform channel must
* ride along unchanged. Pins the modelA hologram regression, where the rebase rebuilt each MeshForm
* and silently dropped its multiply/screen colours, stripping the per-drawable tints off every
* MOC3-imported model (the hologram overlay quad lost the blue that its HardLight blend needed).
*/
class Moc3RestMeshTest {
private val paramA = ParameterId("A")
private val blueMultiply = ColorRgb(0.1f, 0.7f, 1f)
private val warmScreen = ColorRgb(0.2f, 0.1f, 0f)
private fun modelWithChannelledKeyforms(): PuppetModel {
// Built bundled and fanned out, so the fixture matches what an importer actually produces.
val fanned =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0f, 1f))),
listOf(
KeyformCell(intArrayOf(0), MeshForm(FloatArray(6), drawOrder = 400f, opacity = 0.25f, multiplyColor = blueMultiply, screenColor = warmScreen)),
KeyformCell(intArrayOf(1), MeshForm(FloatArray(6) { 2f }, drawOrder = 600f, opacity = 0.75f, multiplyColor = blueMultiply, screenColor = warmScreen)),
),
).fanOutMesh()
val drawable =
Drawable(
id = DrawableId("quad"),
name = "quad",
parentDeformerId = null,
blendMode = BlendMode.HardLight,
maskedBy = emptyList(),
mesh = DrawableMesh(floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f), floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f), intArrayOf(0, 1, 2)),
geometryGrid = fanned.geometry,
channelGrids = fanned.channels,
blendShapes =
listOf(
BlendShapeBinding(
parameterId = paramA,
keys = floatArrayOf(0f, 1f),
neutralIndex = 0,
forms = listOf(null, MeshForm(FloatArray(6) { 1f }, drawOrder = 500f, opacity = 0.5f, multiplyColor = blueMultiply, screenColor = warmScreen)),
),
),
)
return PuppetModel(
parameters = listOf(Parameter(paramA, "A", 0f, 1f, 0f)),
parts = emptyList(),
deformers = emptyList(),
drawables = listOf(drawable),
rootChildren = listOf(OrgChild.Drawable(drawable.id)),
rootPartId = null,
)
}
/**
* The rebase moves geometry only; every channel track must come through untouched.
*
* Since the channel split this is structural - the tracks are a separate field the rebase never
* writes - but it is asserted anyway, because the property is what the rebase is allowed to do, not
* an artefact of how it happens to be written today.
*/
@Test
fun rebasePreservesEveryNonPositionalKeyformChannel() {
val rebased = restMeshesToCanvasSpace(modelWithChannelledKeyforms())
val drawable = rebased.drawables.single()
assertEquals(2, drawable.geometryGrid!!.cells.size)
val channels = drawable.channelGrids
fun scalars(channel: FormChannel): List<Float> =
channels[channel]!!.cells.map { cell -> (cell.form as ChannelValue.Scalar).value }
fun colors(channel: FormChannel): List<ColorRgb> =
channels[channel]!!.cells.map { cell -> (cell.form as ChannelValue.Color).color }
assertEquals(listOf(400f, 600f), scalars(FormChannel.DRAW_ORDER))
assertEquals(listOf(0.25f, 0.75f), scalars(FormChannel.OPACITY))
assertEquals(listOf(blueMultiply, blueMultiply), colors(FormChannel.MULTIPLY_COLOR), "keyform multiply color must survive the rebase")
assertEquals(listOf(warmScreen, warmScreen), colors(FormChannel.SCREEN_COLOR), "keyform screen color must survive the rebase")
val blendForm = drawable.blendShapes.single().forms[1]!!
assertEquals(500f, blendForm.drawOrder)
assertEquals(0.5f, blendForm.opacity)
assertEquals(blueMultiply, blendForm.multiplyColor, "blend-shape multiply color must survive the rebase")
assertEquals(warmScreen, blendForm.screenColor, "blend-shape screen color must survive the rebase")
}
@Test
fun rebaseKeepsAbsoluteKeyformGeometryIntact() {
val original = modelWithChannelledKeyforms()
val rebased = restMeshesToCanvasSpace(original)
val originalDrawable = original.drawables.single()
val rebasedDrawable = rebased.drawables.single()
// base + delta must reconstruct the same absolute positions per cell, whatever base the
// rebase chose - that invariance is the whole contract of the rewrite.
for (cellIndex in 0 until 2) {
val originalForm = originalDrawable.geometryGrid!!.cells[cellIndex].form
val rebasedForm = rebasedDrawable.geometryGrid!!.cells[cellIndex].form
for (coordIndex in 0 until 6) {
assertEquals(
originalDrawable.mesh!!.positions[coordIndex] + originalForm.positionDeltas[coordIndex],
rebasedDrawable.mesh!!.positions[coordIndex] + rebasedForm.positionDeltas[coordIndex],
absoluteTolerance = 1e-4f,
)
}
}
}
private fun assertEquals(expected: Float, actual: Float, absoluteTolerance: Float) {
kotlin.test.assertTrue(
kotlin.math.abs(expected - actual) <= absoluteTolerance,
"expected $expected, got $actual",
)
}
}
@@ -0,0 +1,99 @@
package org.umamo.render
import org.umamo.format.png.PngCodec
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.PuppetModel
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertSame
/**
* The export-side texture helpers, on hand-built inputs.
*
* Both live here rather than in the app layer because they read [PuppetTextures] and touch nothing
* else - which is also what makes them reachable from commonTest at all.
*/
class PuppetExportTexturesTest {
/**
* A drawable with the given id and page binding.
*
* @param String id The drawable id.
* @param Int page Its atlas page, or -1 for the unbound sentinel.
* @return Drawable The drawable.
*/
private fun drawable(id: String, page: Int = -1): Drawable =
Drawable(
id = DrawableId(id),
name = id,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = null,
geometryGrid = null,
texturePage = page,
)
/**
* A model over the given drawables.
*
* @param Drawable drawables The drawables.
* @return PuppetModel The model.
*/
private fun modelOf(vararg drawables: Drawable): PuppetModel =
PuppetModel(
parameters = emptyList(),
parts = emptyList(),
deformers = emptyList(),
drawables = drawables.toList(),
rootChildren = drawables.map { drawable -> OrgChild.Drawable(drawable.id) },
rootPartId = null,
canvasWidth = 0f,
canvasHeight = 0f,
worldOriginX = 0f,
worldOriginZ = 0f,
)
/**
* A texture set binding the given drawable ids to pages.
*
* @param Pair bindings Drawable id to page index.
* @return PuppetTextures The set.
*/
private fun texturesBinding(vararg bindings: Pair<String, Int>): PuppetTextures =
PuppetTextures(emptyList(), bindings.toMap(), premultipliedAlpha = false)
@Test
fun aCmo3OriginDrawableGetsItsPageFromTheDecodedSet() {
// The case the helper exists for: a CMO3 has no page index of its own, so every drawable arrives
// on the -1 sentinel that the moc lowering would otherwise clamp to page 0 - pointing a
// multi-page rig at one atlas.
val bound = withTexturePagesFrom(modelOf(drawable("A"), drawable("B")), texturesBinding("A" to 0, "B" to 2))
assertEquals(listOf(0, 2), bound.drawables.map { it.texturePage })
}
@Test
fun anUnmappedDrawableKeepsWhateverPageItHad() {
val bound = withTexturePagesFrom(modelOf(drawable("A", page = 3), drawable("B")), texturesBinding("A" to 3))
assertEquals(listOf(3, -1), bound.drawables.map { it.texturePage }, "B has no binding to take")
}
@Test
fun aModelWithNothingToMoveIsReturnedUnchanged() {
// Identity, not equality: the caller re-exports this straight into the lowering, and an
// unnecessary copy would defeat every downstream identity check on the model.
val model = modelOf(drawable("A", page = 1))
assertSame(model, withTexturePagesFrom(model, texturesBinding("A" to 1)))
}
@Test
fun anEncodedAtlasPageRoundTripsThroughThePngCodec() {
val page = DecodedImage(ByteArray(5 * 7 * 4) { index -> index.toByte() }, width = 5, height = 7)
val decoded = PngCodec.read(encodeAtlasPng(page))
assertEquals(5, decoded.width)
assertEquals(7, decoded.height)
assertEquals(page.rgba.toList(), decoded.rgba.toList(), "the pixels must survive the re-encode")
}
}
@@ -0,0 +1,80 @@
package org.umamo.render
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertNull
/**
* Contract checks for [buildPuppetTextures], the format-agnostic core both ingest paths end at, and
* for the two opposite [UndecodablePagePolicy] answers layered on it: MOC3 fails the whole build so a
* broken family surfaces as an import error, CMO3 drops the page and keeps the rest of the rig
* openable. Synthetic pixels only - no corpus dependency, so this runs on every target.
*/
class PuppetTexturesTest {
private fun pngOfSize(width: Int, height: Int): ByteArray =
PngCodec.write(RasterImage(width = width, height = height, rgba = ByteArray(width * height * 4) { -1 }))
private val onePixelPng: ByteArray = pngOfSize(1, 1)
private val notAPng: ByteArray = "not a png".encodeToByteArray()
@Test
fun decodesPagesAndKeepsTheIndexMap() {
val textures = buildPuppetTextures(listOf(onePixelPng), mapOf("ArtMesh1" to 0))
assertNotNull(textures)
assertEquals(1, textures.atlases.size, "decoded page count")
assertEquals(1, textures.atlases[0].width, "page width")
assertEquals(0, textures.atlasIndexByDrawableId["ArtMesh1"], "page index for the drawable")
}
@Test
fun undecodablePageFailsTheBuild() {
assertNull(buildPuppetTextures(listOf(notAPng), mapOf("ArtMesh1" to 0)))
}
@Test
fun outOfRangePageIndexFailsTheBuild() {
assertNull(buildPuppetTextures(listOf(onePixelPng), mapOf("ArtMesh1" to 1)), "index past the page list")
assertNull(buildPuppetTextures(listOf(onePixelPng), mapOf("ArtMesh1" to -1)), "negative index")
}
@Test
fun skipPolicyDropsOnlyTheDrawablesOnTheBrokenPage() {
val textures =
buildPuppetTextures(
listOf(pngOfSize(1, 1), notAPng, pngOfSize(2, 2)),
mapOf("ArtMeshFirst" to 0, "ArtMeshBroken" to 1, "ArtMeshLast" to 2),
undecodablePage = UndecodablePagePolicy.Skip,
)
assertNotNull(textures, "Skip never fails the build")
assertEquals(2, textures.atlases.size, "the undecodable page is dropped")
assertNull(textures.atlasIndexByDrawableId["ArtMeshBroken"], "its drawable is unmapped, not left dangling")
assertEquals(0, textures.atlasIndexByDrawableId["ArtMeshFirst"], "an earlier page keeps its slot")
// The renumbering is the whole point: page 2 became page 1 when page 1 went away, and a stale 2
// here would index past the list and crash PuppetRenderer's direct lookup at first frame.
assertEquals(1, textures.atlasIndexByDrawableId["ArtMeshLast"], "a later page is renumbered down")
assertEquals(2, textures.atlases[1].width, "the renumbered slot holds the page it claims to")
}
@Test
fun skipPolicyToleratesAnOutOfRangeIndex() {
val textures =
buildPuppetTextures(
listOf(onePixelPng),
mapOf("ArtMeshOk" to 0, "ArtMeshStale" to 7),
undecodablePage = UndecodablePagePolicy.Skip,
)
assertNotNull(textures)
assertEquals(0, textures.atlasIndexByDrawableId["ArtMeshOk"])
assertNull(textures.atlasIndexByDrawableId["ArtMeshStale"], "an unresolvable page number drops the drawable")
}
@Test
fun premultipliedFlagIsCarriedThrough() {
val textures = buildPuppetTextures(listOf(onePixelPng), mapOf("ArtMesh1" to 0), premultipliedAlpha = true)
assertNotNull(textures)
assertEquals(true, textures.premultipliedAlpha)
}
}
@@ -0,0 +1,314 @@
package org.umamo.render
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import org.umamo.runtime.model.AtlasPlacement
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.DrawableLayerBinding
import org.umamo.runtime.model.applyUvAffine
import org.umamo.runtime.model.atlasPixelOf
import org.umamo.runtime.model.identityUvAffine
import org.umamo.runtime.model.invertUvAffine
import org.umamo.runtime.model.layerPixelOf
import org.umamo.runtime.model.layerUvAffineOf
import org.umamo.runtime.model.layerUvsFromAtlasUvs
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.test.assertSame
import kotlin.test.assertTrue
/**
* Pins the source-layer store and the atlas-placement recovery math: the TRS round-trip across every
* shape the corpus contains (translation, quarter turns, free angles, non-unit and mirroring scale,
* fractional origins), the uv mapping in both the packed and unpacked cases, and the store's
* decode-once caching including its remembered failures.
*
* The recovery convention this locks - forward is `atlas = R(angle) . S . layer + position` in
* page pixels with y running down - is cross-checked against real files by
* Cmo3AtlasIngestCorpusTest (`:interop`), which composes it against the format's own
* atlas-to-canvas affine.
*/
class SourceArtRastersTest {
private fun placementOf(
positionX: Float = 0f,
positionY: Float = 0f,
scaleX: Float = 1f,
scaleY: Float = 1f,
rotationDegrees: Float = 0f,
): AtlasPlacement =
AtlasPlacement(
pageIndex = 0,
positionX = positionX,
positionY = positionY,
scaleX = scaleX,
scaleY = scaleY,
rotationDegrees = rotationDegrees,
)
private fun assertRoundTrips(placement: AtlasPlacement, layerX: Float, layerY: Float, message: String) {
val atlasPixel = atlasPixelOf(placement, layerX, layerY)
val recovered = layerPixelOf(placement, atlasPixel[0], atlasPixel[1])
assertNotNull(recovered, "$message: the inverse must resolve")
assertEquals(layerX, recovered[0], 1e-3f, "$message: x")
assertEquals(layerY, recovered[1], 1e-3f, "$message: y")
}
/** Every placement shape the corpus contains inverts back to the point it started from. */
@Test
fun placementInversionRoundTripsEveryShape() {
assertRoundTrips(placementOf(), 12f, 34f, "identity")
assertRoundTrips(placementOf(positionX = 640f, positionY = 128f), 12f, 34f, "translation")
assertRoundTrips(placementOf(positionX = 6742.03f, positionY = 6710.03f), 12f, 34f, "fractional origin")
assertRoundTrips(placementOf(rotationDegrees = 90f), 12f, 34f, "quarter turn")
assertRoundTrips(placementOf(rotationDegrees = 180f, positionX = 50f), 12f, 34f, "half turn")
assertRoundTrips(placementOf(rotationDegrees = 37.5f, positionY = 9f), 12f, 34f, "free angle")
assertRoundTrips(placementOf(scaleX = 0.8588867f, scaleY = 0.8588867f), 12f, 34f, "uniform scale")
assertRoundTrips(placementOf(scaleX = 2f, scaleY = 0.5f), 12f, 34f, "anisotropic scale")
assertRoundTrips(placementOf(scaleX = -1f), 12f, 34f, "horizontal mirror")
assertRoundTrips(placementOf(scaleY = -1f), 12f, 34f, "vertical mirror")
assertRoundTrips(
placementOf(positionX = 292.0f, positionY = 409.0863f, scaleX = 1.16431f, scaleY = 1.16431f, rotationDegrees = 90f),
12f,
34f,
"rotated, scaled and offset together",
)
}
/**
* The forward transform's orientation, stated explicitly so a sign flip cannot hide behind a
* round-trip (which passes for either convention). A 90 degree rotation with y running DOWN
* carries the +x axis onto +y.
*/
@Test
fun quarterTurnCarriesTheXAxisOntoY() {
val turned = atlasPixelOf(placementOf(rotationDegrees = 90f), 10f, 0f)
assertEquals(0f, turned[0], 1e-3f, "a quarter turn zeroes the x component")
assertEquals(10f, turned[1], 1e-3f, "a quarter turn carries +x onto +y")
}
/** A degenerate placement (a collapsed axis) has no inverse and must report that, not divide by zero. */
@Test
fun degeneratePlacementHasNoInverse() {
assertNull(layerPixelOf(placementOf(scaleX = 0f), 5f, 5f), "a zero x scale cannot be inverted")
assertNull(layerPixelOf(placementOf(scaleY = 0f), 5f, 5f), "a zero y scale cannot be inverted")
}
/** A packed drawable's uvs scale up to page pixels, invert, and scale down by the layer's own size. */
@Test
fun packedUvsMapIntoTheLayerFrame() {
// A 64x64 layer packed unrotated at (128, 256) on a 512x512 page: the layer's own corners land
// at page (128, 256) and (192, 320), i.e. uv (0.25, 0.5) and (0.375, 0.625).
val binding =
DrawableLayerBinding(
layerKey = "layer",
placement = placementOf(positionX = 128f, positionY = 256f),
pageWidth = 512,
pageHeight = 512,
)
val layerUvs =
layerUvsFromAtlasUvs(floatArrayOf(0.25f, 0.5f, 0.375f, 0.625f), binding, layerWidth = 64, layerHeight = 64)
assertNotNull(layerUvs, "a well-formed binding maps")
assertEquals(0f, layerUvs[0], 1e-4f, "the layer's own origin maps to uv 0")
assertEquals(0f, layerUvs[1], 1e-4f, "the layer's own origin maps to uv 0")
assertEquals(1f, layerUvs[2], 1e-4f, "the layer's far corner maps to uv 1")
assertEquals(1f, layerUvs[3], 1e-4f, "the layer's far corner maps to uv 1")
}
/**
* An unpacked drawable's uvs already address its layer image (ingest inverted the logical-frame
* affine at import), so recovery must leave them alone - applying a placement would double-transform.
*/
@Test
fun unpackedUvsPassThroughUntouched() {
val binding = DrawableLayerBinding(layerKey = "layer", placement = null, pageWidth = 0, pageHeight = 0)
val atlasUvs = floatArrayOf(0.1f, 0.2f, 0.9f, 0.8f)
val layerUvs = layerUvsFromAtlasUvs(atlasUvs, binding, layerWidth = 64, layerHeight = 64)
assertNotNull(layerUvs, "an unpacked binding maps")
assertTrue(layerUvs.contentEquals(atlasUvs), "unpacked uvs must survive verbatim")
}
/**
* The uv affine and its inverse are the round trip a layer-view EDIT depends on: a coordinate
* authored over the art must reach the stored atlas frame and back unchanged. Checked over every
* placement shape the corpus contains, since a rotation or a mirror is exactly where an inverse
* goes wrong quietly.
*/
@Test
fun uvAffineRoundTripsThroughItsInverse() {
val shapes =
listOf(
"identity" to placementOf(),
"translation" to placementOf(positionX = 640f, positionY = 128f),
"fractional origin" to placementOf(positionX = 6742.03f, positionY = 6710.03f),
"quarter turn" to placementOf(rotationDegrees = 90f),
"free angle" to placementOf(rotationDegrees = 37.5f, positionY = 9f),
"uniform scale" to placementOf(scaleX = 0.8588867f, scaleY = 0.8588867f),
"anisotropic scale" to placementOf(scaleX = 2f, scaleY = 0.5f),
"horizontal mirror" to placementOf(scaleX = -1f),
"rotated, scaled and offset" to
placementOf(positionX = 292f, positionY = 409.0863f, scaleX = 1.16431f, scaleY = 1.16431f, rotationDegrees = 90f),
)
val storedUvs = floatArrayOf(0.1f, 0.2f, 0.9f, 0.8f, 0.5f, 0.5f)
for ((label, placement) in shapes) {
val binding = DrawableLayerBinding("layer", placement, pageWidth = 2048, pageHeight = 1024)
val toLayer = layerUvAffineOf(binding, layerWidth = 576, layerHeight = 646)
assertNotNull(toLayer, "$label: the layer affine resolves")
val toStored = invertUvAffine(toLayer)
assertNotNull(toStored, "$label: the affine inverts")
val roundTripped = applyUvAffine(applyUvAffine(storedUvs, toLayer), toStored)
for (componentIndex in storedUvs.indices) {
assertEquals(storedUvs[componentIndex], roundTripped[componentIndex], 1e-4f, "$label: component $componentIndex")
}
}
}
/** An unpacked drawable's mapping is the identity in BOTH directions, not a placement inverse. */
@Test
fun unpackedBindingYieldsTheIdentityAffine() {
val binding = DrawableLayerBinding("layer", placement = null, pageWidth = 0, pageHeight = 0)
val toLayer = layerUvAffineOf(binding, layerWidth = 64, layerHeight = 64)
assertNotNull(toLayer, "an unpacked binding still maps")
assertTrue(toLayer.contentEquals(identityUvAffine()), "an unpacked mapping is the identity")
val toStored = invertUvAffine(toLayer)
assertNotNull(toStored, "the identity inverts")
val storedUvs = floatArrayOf(0.1f, 0.2f, 0.9f, 0.8f)
assertTrue(applyUvAffine(storedUvs, toStored).contentEquals(storedUvs), "and changes nothing coming back")
}
/** A mapping that cannot be formed reports it rather than producing a wrong one. */
@Test
fun degenerateMappingsResolveToNothing() {
val degenerate = DrawableLayerBinding("layer", placementOf(scaleX = 0f), pageWidth = 512, pageHeight = 512)
assertNull(layerUvAffineOf(degenerate, 64, 64), "a collapsed placement axis has no mapping")
val sane = DrawableLayerBinding("layer", placementOf(), pageWidth = 512, pageHeight = 512)
assertNull(layerUvAffineOf(sane, layerWidth = 0, layerHeight = 64), "a zero-width layer has no mapping")
assertNull(invertUvAffine(floatArrayOf(0f, 0f, 5f, 0f, 0f, 5f)), "a collapsed affine does not invert")
}
/** A layer with no usable size cannot host a mapping; report it rather than dividing by zero. */
@Test
fun zeroSizedLayerHasNoMapping() {
val binding =
DrawableLayerBinding(layerKey = "layer", placement = placementOf(), pageWidth = 512, pageHeight = 512)
assertNull(layerUvsFromAtlasUvs(floatArrayOf(0f, 0f), binding, layerWidth = 0, layerHeight = 64), "zero width")
assertNull(layerUvsFromAtlasUvs(floatArrayOf(0f, 0f), binding, layerWidth = 64, layerHeight = 0), "zero height")
}
private fun onePixelPng(): ByteArray = PngCodec.write(RasterImage(1, 1, byteArrayOf(1, 2, 3, 4)))
/** The store decodes a tile once and serves the same instance afterwards. */
@Test
fun rasterDecodesOnceAndCaches() {
var readCount = 0
val store =
SourceArtRasters.fromPng { _ ->
readCount++
onePixelPng()
}
val first = store.rasterFor(AtlasTileId("a"))
val second = store.rasterFor(AtlasTileId("a"))
assertNotNull(first, "the tile decodes")
assertSame(first, second, "a decoded tile is cached, not re-decoded")
assertEquals(1, readCount, "the byte supplier is consulted once")
}
/** A failed decode is remembered as a failure, not retried on every request. */
@Test
fun rasterRemembersFailures() {
var readCount = 0
val store =
SourceArtRasters.fromPng { _ ->
readCount++
byteArrayOf(0, 1, 2)
}
assertNull(store.rasterFor(AtlasTileId("a")), "undecodable bytes yield no raster")
assertNull(store.rasterFor(AtlasTileId("a")), "still no raster on a second request")
assertEquals(1, readCount, "a remembered failure is not retried")
}
/**
* A store over already-decoded rasters (an artwork-origin document) hands out the SAME instance from
* its cached and its uncached read: the renderer's texture cache and the viewport's freshness test
* compare decoded images by identity, so a fresh wrapper per call would read as a changed image.
*/
@Test
fun aDecodedStoreSharesOneInstanceAcrossBothReads() {
val image = DecodedImage(byteArrayOf(1, 2, 3, 4), 1, 1)
val store = SourceArtRasters { requested -> if (requested == AtlasTileId("a")) image else null }
assertSame(image, store.rasterFor(AtlasTileId("a")), "the cached read hands out the supplied instance")
assertSame(image, store.decodeRaster(AtlasTileId("a")), "so does the uncached read")
assertNull(store.decodeRaster(AtlasTileId("b")), "an unknown tile has no raster either way")
}
/**
* Rasters added after the store was built (artwork brought into an open document) read from both
* twins and never shadow what the decoder already answers for other tiles.
*/
@Test
fun addedRastersReadFromBothTwinsWithoutShadowingTheDecoder() {
val decoded = DecodedImage(byteArrayOf(1, 2, 3, 4), 1, 1)
val store = SourceArtRasters { requested -> if (requested == AtlasTileId("base")) decoded else null }
val added = DecodedImage(byteArrayOf(5, 6, 7, 8), 1, 1)
store.addDecoded(mapOf(AtlasTileId("new") to added))
assertSame(added, store.decodeRaster(AtlasTileId("new")), "the uncached read sees the added raster")
assertSame(added, store.rasterFor(AtlasTileId("new")), "so does the cached one")
assertSame(decoded, store.rasterFor(AtlasTileId("base")), "the decoder's own tiles are untouched")
assertNull(store.rasterFor(AtlasTileId("missing")), "an unknown tile is still unknown")
}
/**
* A raster added for a tile the cached read already answered replaces that answer: a reload's
* replacement id is minted against the model as it stands, so reload, undo, reload reuses the id
* with new pixels, and the cache must not keep handing out the first reload's.
*/
@Test
fun anAddedRasterReplacesACachedOneForTheSameTile() {
val first = DecodedImage(byteArrayOf(1, 2, 3, 4), 1, 1)
val second = DecodedImage(byteArrayOf(5, 6, 7, 8), 1, 1)
val store = SourceArtRasters { null }
val reused = AtlasTileId("art-0/lyid:1~1")
store.addDecoded(mapOf(reused to first))
assertSame(first, store.rasterFor(reused), "the cached read takes the first reload's pixels")
store.addDecoded(mapOf(reused to second))
assertSame(second, store.rasterFor(reused), "and the second reload's once they replace them")
assertSame(second, store.decodeRaster(reused), "the same instance from the uncached read")
// A tile the cache learned as absent is likewise superseded by an added raster.
val late = AtlasTileId("late")
assertNull(store.rasterFor(late))
store.addDecoded(mapOf(late to first))
assertSame(first, store.rasterFor(late), "a remembered miss does not outlive the raster's arrival")
}
/**
* Two stores never share what was added to one of them.
*
* Documents hand their own store to every artwork import, which decodes into it - so a store shared
* between documents would read one document's art back out under the next document's tile ids.
*/
@Test
fun addedRastersStayInTheStoreTheyWereAddedTo() {
val tileId = AtlasTileId("tile-1")
val store = SourceArtRasters { null }
val other = SourceArtRasters { null }
store.addDecoded(mapOf(tileId to DecodedImage(ByteArray(4) { 0xFF.toByte() }, 1, 1)))
assertNotNull(store.rasterFor(tileId), "the store it was added to has it")
assertNull(other.rasterFor(tileId), "another document's store does not")
}
/** A tile the supplier has no bytes for decodes to nothing, and a store over no pixels has none at all. */
@Test
fun aTileWithoutBytesDecodesToNothing() {
val known = AtlasTileId("a")
val store = SourceArtRasters.fromPng { requested -> if (requested == known) onePixelPng() else null }
assertNotNull(store.rasterFor(known), "a known tile decodes")
assertNull(store.rasterFor(AtlasTileId("missing")), "an unknown tile has no bytes")
assertNull(SourceArtRasters { null }.rasterFor(known), "a store over no pixels at all has no rasters")
}
}
@@ -0,0 +1,143 @@
package org.umamo.render
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* Exercises the pure viewport-camera maths (no GL): fit framing, the world-to-NDC affine, cursor-pinned
* zoom, grab pan, actual-size, and the zoom clamps. These are the invariants the interactive navigation
* relies on, isolated so they verify without a render context.
*/
class ViewportCameraTest {
private val tolerance = 1e-3f
/** Maps a world point to a screen pixel (top-left origin) through a camera, for round-trip assertions. */
private fun worldToScreen(camera: ViewportCamera, worldX: Float, worldZ: Float, width: Int, height: Int): Pair<Float, Float> {
val ndc = camera.worldToNdc(width, height)
val ndcX = worldX * ndc[0] + ndc[2]
val ndcY = worldZ * ndc[1] + ndc[3]
return Pair((ndcX + 1f) / 2f * width, (1f - ndcY) / 2f * height)
}
@Test
fun fitCentersAndScalesContent() {
val content = ContentBounds(minX = -100f, minY = -50f, width = 200f, height = 100f)
val camera = ViewportCamera.fit(content, viewportWidth = 400, viewportHeight = 400)
assertEquals(0f, camera.centerX, tolerance, "center X = content center")
assertEquals(0f, camera.centerY, tolerance, "center Y = content center")
// min(400/200, 400/100) = 2, times the 0.9 margin.
assertEquals(0.9f * 2f, camera.zoom, tolerance, "fit zoom uses the tighter axis and the margin")
}
@Test
fun worldToNdcMapsCenterToOriginAndOneUnitToZoomPixels() {
val camera = ViewportCamera(centerX = 5f, centerY = -7f, zoom = 3f)
val width = 200
val height = 100
val ndc = camera.worldToNdc(width, height)
val centerX = camera.centerX * ndc[0] + ndc[2]
val centerY = camera.centerY * ndc[1] + ndc[3]
assertEquals(0f, centerX, tolerance, "camera center maps to NDC origin")
assertEquals(0f, centerY, tolerance, "camera center maps to NDC origin")
// One world unit right of center lands zoom pixels right of the viewport center.
val (screenX, screenY) = worldToScreen(camera, camera.centerX + 1f, camera.centerY, width, height)
assertEquals(width / 2f + camera.zoom, screenX, tolerance, "one world unit = zoom pixels")
assertEquals(height / 2f, screenY, tolerance, "no vertical shift along a horizontal step")
}
@Test
fun zoomAtCursorPinsTheWorldPointUnderTheCursor() {
// Start on the grid (150%) so the +25% step lands cleanly at 175%, isolating the pin assertion.
val camera = ViewportCamera(centerX = 10f, centerY = 20f, zoom = 1.5f)
val width = 320
val height = 240
val cursorX = 250f
val cursorY = 60f
// The world point currently under the cursor (the camera's own inverse).
val worldX = camera.centerX + (cursorX - width / 2f) / camera.zoom
val worldZ = camera.centerY + (height / 2f - cursorY) / camera.zoom
val zoomed = camera.zoomAtCursorByPercent(deltaPercent = 25f, stepPercent = 1f, cursorXpx = cursorX, cursorYpx = cursorY, viewportWidth = width, viewportHeight = height)
assertEquals(1.75f, zoomed.zoom, tolerance, "150% + 25 points = 175%")
val (screenX, screenY) = worldToScreen(zoomed, worldX, worldZ, width, height)
assertEquals(cursorX, screenX, tolerance, "the pinned world point stays under the cursor X")
assertEquals(cursorY, screenY, tolerance, "the pinned world point stays under the cursor Y")
}
@Test
fun zoomSnapsOffGridFitToWholePercents() {
// A fit ratio is arbitrary (41.3%); +1% steps must snap onto the integer-percent grid and reach 100.
var camera = ViewportCamera(centerX = 0f, centerY = 0f, zoom = 0.413f)
camera = camera.zoomedByPercent(deltaPercent = 1f, stepPercent = 1f)
assertEquals(42f, camera.zoom * 100f, 0.5f, "first +1% step snaps onto the integer grid")
// 58 more +1% steps reach exactly 100%.
repeat(58) { camera = camera.zoomedByPercent(deltaPercent = 1f, stepPercent = 1f) }
assertEquals(1f, camera.zoom, tolerance, "stepping reaches exactly 100%")
// A +5% step from 100% snaps onto the 5-grid at 105%.
val coarse = camera.zoomedByPercent(deltaPercent = 5f, stepPercent = 5f)
assertEquals(1.05f, coarse.zoom, tolerance, "5% steps snap onto the 5-percent grid")
}
@Test
fun panByScreenMovesCenterByDeltaOverZoom() {
val camera = ViewportCamera(centerX = 0f, centerY = 0f, zoom = 2f)
val panned = camera.panByScreen(deltaXpx = 10f, deltaYpx = 6f)
assertEquals(-5f, panned.centerX, tolerance, "center X shifts opposite the drag, scaled by 1/zoom")
assertEquals(3f, panned.centerY, tolerance, "center Y carries the screen-down vs world-up flip")
}
@Test
fun actualSizeSetsUnitZoomKeepingCenter() {
val camera = ViewportCamera(centerX = 42f, centerY = -9f, zoom = 7f)
val actual = camera.withActualSize()
assertEquals(1f, actual.zoom, tolerance, "actual size is true 1:1")
assertEquals(camera.centerX, actual.centerX, tolerance, "center is unchanged")
assertEquals(camera.centerY, actual.centerY, tolerance, "center is unchanged")
}
@Test
fun framingScreenRectCentersAndFillsTheBox() {
val camera = ViewportCamera(centerX = 10f, centerY = 20f, zoom = 2f)
val width = 400
val height = 300
// A 100x60 box; corners passed reversed to prove the two corners may be given in any order.
val left = 50f
val top = 40f
val right = 150f
val bottom = 100f
val framed = camera.framingScreenRect(right, bottom, left, top, viewportWidth = width, viewportHeight = height)
// min(400/100, 300/60) = min(4, 5) = 4, so the looser (vertical) axis letterboxes.
assertEquals(camera.zoom * 4f, framed.zoom, tolerance, "the box fills the tighter axis")
// The world point under the box center (via the OLD camera inverse) maps to the viewport center
// under the NEW camera.
val worldX = camera.centerX + ((left + right) / 2f - width / 2f) / camera.zoom
val worldZ = camera.centerY + (height / 2f - (top + bottom) / 2f) / camera.zoom
val (screenX, screenY) = worldToScreen(framed, worldX, worldZ, width, height)
assertEquals(width / 2f, screenX, tolerance, "box center X frames to viewport center")
assertEquals(height / 2f, screenY, tolerance, "box center Y frames to viewport center")
}
@Test
fun framingTinyRectClampsToMaxZoom() {
val camera = ViewportCamera(centerX = 0f, centerY = 0f, zoom = 1f)
val framed = camera.framingScreenRect(100f, 100f, 100.5f, 100.5f, viewportWidth = 800, viewportHeight = 800)
assertEquals(ViewportCamera.MAX_ZOOM, framed.zoom, tolerance, "a sub-pixel box cannot exceed the ceiling")
}
@Test
fun framingDegenerateRectIsGuarded() {
val camera = ViewportCamera(centerX = 3f, centerY = -4f, zoom = 2f)
// Zero-area (a click, not a drag): the 1px floor keeps the zoom finite and clamped.
val framed = camera.framingScreenRect(200f, 150f, 200f, 150f, viewportWidth = 400, viewportHeight = 300)
assertTrue(framed.zoom in ViewportCamera.MIN_ZOOM..ViewportCamera.MAX_ZOOM, "zoom stays within the clamps")
}
@Test
fun zoomClampsAtTheLimits() {
val far = ViewportCamera(0f, 0f, ViewportCamera.MAX_ZOOM).zoomedByPercent(deltaPercent = 100_000f, stepPercent = 5f)
assertEquals(ViewportCamera.MAX_ZOOM, far.zoom, tolerance, "cannot exceed the ceiling")
val near = ViewportCamera(0f, 0f, ViewportCamera.MIN_ZOOM).zoomedByPercent(deltaPercent = -100_000f, stepPercent = 5f)
assertEquals(ViewportCamera.MIN_ZOOM, near.zoom, tolerance, "cannot drop below the floor")
assertTrue(ViewportCamera.MIN_ZOOM < ViewportCamera.MAX_ZOOM, "floor below ceiling")
}
}
@@ -0,0 +1,215 @@
package org.umamo.render.eval
import org.umamo.runtime.keyform.asGeometryGrid
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.BlendWeightLimit
import org.umamo.runtime.model.BlendWeightLimitPoint
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
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.MeshForm
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.WarpForm
import org.umamo.runtime.model.WarpLatticeForm
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* Pins the blend-shape weight machinery: the epsilon-free saturating bracket with neutral
* suppression, the min-combined limit curves, and the grid-at-default delta reference.
*/
class BlendShapeEvalTest {
private val shrink = ParameterId("ParamShrink")
private val gate = ParameterId("ParamGate")
/** Value lookup from explicit pairs; everything else 0. */
private fun values(vararg pairs: Pair<ParameterId, Float>): (ParameterId) -> Float {
val map = mapOf(*pairs)
return { map[it] ?: 0f }
}
private fun binding(
keys: FloatArray,
neutralIndex: Int,
forms: List<WarpForm?>,
limits: List<BlendWeightLimit> = emptyList(),
) = BlendShapeBinding(shrink, keys, neutralIndex, forms, limits)
private val twoKey =
binding(
keys = floatArrayOf(-1f, 0f),
neutralIndex = 1,
forms = listOf(WarpForm(floatArrayOf(10f, 20f)), null),
)
/** At the neutral value the active list is EMPTY - the default pose is arithmetic-free. */
@Test
fun neutralValueContributesNothing() {
assertTrue(activeBlendKeys(twoKey, 0f, 1f).isEmpty(), "at neutral")
assertTrue(activeBlendKeys(twoKey, 0.5f, 1f).isEmpty(), "beyond the neutral end saturates to neutral = nothing")
}
/** Bracket interpolation between a key and the neutral: only the non-neutral key contributes. */
@Test
fun bracketInterpolatesTowardNeutral() {
val atKey = activeBlendKeys(twoKey, -1f, 1f)
assertEquals(1, atKey.size)
assertEquals(0, atKey[0].keyIndex)
assertEquals(1f, atKey[0].weight)
val half = activeBlendKeys(twoKey, -0.5f, 1f)
assertEquals(1, half.size)
assertEquals(0.5f, half[0].weight, "midpoint weights the key half")
}
/** Out-of-range driving values SATURATE (Umamo C++ Runtime verdict): the end delta is held. */
@Test
fun outOfRangeSaturates() {
val beyond = activeBlendKeys(twoKey, -1.5f, 1f)
assertEquals(1, beyond.size)
assertEquals(0, beyond[0].keyIndex)
assertEquals(1f, beyond[0].weight, "beyond the far key holds its full delta")
}
/** Between two non-neutral keys both contribute, weights summing to the limit multiplier. */
@Test
fun bracketBetweenTwoNonNeutralKeys() {
val threeKey =
binding(
keys = floatArrayOf(0f, 1f, 2f),
neutralIndex = 0,
forms = listOf(null, WarpForm(floatArrayOf(1f, 1f)), WarpForm(floatArrayOf(2f, 2f))),
)
val between = activeBlendKeys(threeKey, 1.25f, 1f)
assertEquals(2, between.size)
assertEquals(1, between[0].keyIndex)
assertEquals(0.75f, between[0].weight)
assertEquals(2, between[1].keyIndex)
assertEquals(0.25f, between[1].weight)
}
/** The limit multiplier scales weights linearly (Model B-measured: a half ramp gives exactly 0.5x). */
@Test
fun limitRampScalesWeights() {
val ramp = listOf(BlendWeightLimit(gate, listOf(BlendWeightLimitPoint(0f, 0f), BlendWeightLimitPoint(1f, 1f))))
assertEquals(0f, limitMultiplier(ramp, values(gate to 0f)), "closed gate suppresses")
assertEquals(0.5f, limitMultiplier(ramp, values(gate to 0.5f)), "half-open gate halves")
assertEquals(1f, limitMultiplier(ramp, values(gate to 1f)), "open gate passes")
assertEquals(0f, limitMultiplier(ramp, values(gate to -1f)), "end-clamped below")
assertEquals(1f, limitMultiplier(ramp, values(gate to 2f)), "end-clamped above")
}
/** Multiple limits combine by MINIMUM, not product (Model C-shaped inverse ramps). */
@Test
fun limitsCombineByMinimum() {
val inverseRamp = { parameter: ParameterId ->
BlendWeightLimit(parameter, listOf(BlendWeightLimitPoint(0f, 1f), BlendWeightLimitPoint(1f, 0f)))
}
val other = ParameterId("ParamOther")
val limits = listOf(inverseRamp(gate), inverseRamp(other))
// gate=0.6 -> 0.4; other=0.8 -> 0.2; MIN = 0.2 (a product would give 0.08).
assertEquals(0.2f, limitMultiplier(limits, values(gate to 0.6f, other to 0.8f)), 1e-6f)
}
/** meshBlendState resolves the grid-at-default reference and stacks bindings by summation. */
@Test
fun meshBlendStateUsesGridAtDefaultReference() {
val axis = ParameterId("ParamAxis")
// Grid keyed on ParamAxis with keys [0 (default), 1]: the default cell carries deltas (5, 0).
val grid =
KeyformGrid(
listOf(KeyformAxis(axis, floatArrayOf(0f, 1f))),
listOf(
KeyformCell(intArrayOf(0), MeshDeltaForm(floatArrayOf(5f, 0f))),
KeyformCell(intArrayOf(1), MeshDeltaForm(floatArrayOf(9f, 0f))),
),
)
val meshBinding =
BlendShapeBinding(
parameterId = shrink,
keys = floatArrayOf(-1f, 0f),
neutralIndex = 1,
forms = listOf(MeshForm(floatArrayOf(11f, 4f)), null),
)
val drawable =
Drawable(
id = DrawableId("d"),
name = "d",
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = null,
geometryGrid = grid,
blendShapes = listOf(meshBinding),
)
val state = meshBlendState(drawable, values(shrink to -1f), values())
assertTrue(state != null)
assertEquals(1, state.contributions.size)
assertEquals(1f, state.contributions[0].weight)
// Reference = the default-pose grid form's deltas: (5, 0).
assertEquals(listOf(5f, 0f), state.referenceDeltas?.toList())
// The eval adds w * (form - reference) = (11-5, 4-0) = (6, 4) on top of the grid result.
}
/** Warp blend deltas subtract the lattice's default-pose grid form (absolute forms). */
@Test
fun warpBlendDeltasSubtractDefaultLattice() {
val axis = ParameterId("ParamAxis")
val grid =
KeyformGrid(
listOf(KeyformAxis(axis, floatArrayOf(0f, 1f))),
listOf(
KeyformCell(intArrayOf(0), WarpForm(floatArrayOf(100f, 100f))),
KeyformCell(intArrayOf(1), WarpForm(floatArrayOf(120f, 100f))),
),
)
val warp =
Deformer.Warp(
id = DeformerId("w"),
name = "w",
parent = null,
partId = null,
rows = 1,
columns = 1,
isQuadTransform = true,
geometryGrid = grid.asGeometryGrid { form -> WarpLatticeForm(form.controlPoints) },
blendShapes =
listOf(
BlendShapeBinding(
parameterId = shrink,
keys = floatArrayOf(-1f, 0f),
neutralIndex = 1,
forms = listOf(WarpForm(floatArrayOf(107f, 103f)), null),
),
),
)
val deltas = warpBlendDeltas(warp, values(shrink to -0.5f), values())
assertTrue(deltas != null)
// Reference = default lattice (100, 100); authored (107, 103); weight 0.5 -> (3.5, 1.5).
assertEquals(3.5f, deltas[0], 1e-6f)
assertEquals(1.5f, deltas[1], 1e-6f)
}
/** A binding-free drawable resolves to null state - the caller keeps today's exact path. */
@Test
fun bindingFreeDrawableHasNoState() {
val bare =
Drawable(
id = DrawableId("d"),
name = "d",
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = null,
geometryGrid = null,
)
assertEquals(null, meshBlendState(bare, values(), values()))
}
}
@@ -0,0 +1,116 @@
package org.umamo.render.eval
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.KeyableTarget
import org.umamo.runtime.model.KeyformAxis
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.KeyformOwner
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.PuppetModel
import kotlin.test.Test
import kotlin.test.assertEquals
/**
* Pins that a pending unkeyed channel edit reaches the renderer.
*
* A pending edit is session state, never document state - so it cannot ride the model to the renderer and
* instead travels beside the pose, exactly as the pose itself travels beside the model. Without this the
* field would show a value the puppet does not reflect, which defeats the point of adjusting before keying.
*
* The override wins over BOTH a stored track and the static fallback, because it represents the value the
* user is looking at right now.
*/
class ChannelOverrideEvalTest {
private val paramA = ParameterId("A")
private val drawableId = DrawableId("d")
private val owner = KeyformOwner.Drawable(drawableId)
private fun model(channelGrids: org.umamo.runtime.model.ChannelGrids): PuppetModel {
val positions = floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f)
val drawable =
Drawable(
id = drawableId,
name = "d",
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(positions, FloatArray(positions.size), intArrayOf(0, 1, 2)),
geometryGrid =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0f))),
listOf(KeyformCell(intArrayOf(0), MeshDeltaForm(FloatArray(positions.size)))),
),
channelGrids = channelGrids,
opacity = 0.25f,
multiplyColor = ColorRgb(1f, 1f, 1f),
)
return PuppetModel(
parameters = listOf(Parameter(paramA, "A", -1f, 1f, 0f)),
parts = emptyList(),
deformers = emptyList(),
drawables = listOf(drawable),
rootChildren = listOf(OrgChild.Drawable(drawableId)),
rootPartId = null,
)
}
/** With no override, the channel reads its static as usual - the parameter is inert by default. */
@Test
fun withoutAnOverrideTheStaticHolds() {
val inputs = preparePose(model(org.umamo.runtime.model.ChannelGrids.Empty), emptyMap())
assertEquals(0.25f, inputs.drawables.single().opacity)
}
/** An override replaces the static for an untracked channel. */
@Test
fun anOverrideBeatsTheStatic() {
val overrides = mapOf(KeyableTarget(owner, FormChannel.OPACITY) to ChannelValue.Scalar(0.9f))
val inputs = preparePose(model(org.umamo.runtime.model.ChannelGrids.Empty), emptyMap(), overrides)
assertEquals(0.9f, inputs.drawables.single().opacity, "the typed value is what the viewport shows")
}
/**
* An override beats a STORED TRACK too.
*
* This is the case that matters: editing a property that is already keyed is precisely when the value
* on screen must follow what was typed rather than what the grid evaluates, or the field and the puppet
* disagree while the user decides whether to key it.
*/
@Test
fun anOverrideBeatsAStoredTrack() {
val track =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(-1f, 1f))),
listOf(
KeyformCell<ChannelValue>(intArrayOf(0), ChannelValue.Scalar(0f)),
KeyformCell<ChannelValue>(intArrayOf(1), ChannelValue.Scalar(1f)),
),
)
val keyed = org.umamo.runtime.model.ChannelGrids(mapOf(FormChannel.OPACITY to track))
val withoutOverride = preparePose(model(keyed), mapOf(paramA to 0f))
assertEquals(0.5f, withoutOverride.drawables.single().opacity, "the track blends to its midpoint")
val overrides = mapOf(KeyableTarget(owner, FormChannel.OPACITY) to ChannelValue.Scalar(0.1f))
val withOverride = preparePose(model(keyed), mapOf(paramA to 0f), overrides)
assertEquals(0.1f, withOverride.drawables.single().opacity, "the pending edit wins over the stored key")
}
/** Colors override the same way, and an override on one channel leaves the others alone. */
@Test
fun anOverrideIsScopedToItsChannel() {
val overrides = mapOf(KeyableTarget(owner, FormChannel.MULTIPLY_COLOR) to ChannelValue.Color(ColorRgb(1f, 0f, 0f)))
val resolved = preparePose(model(org.umamo.runtime.model.ChannelGrids.Empty), emptyMap(), overrides).drawables.single()
assertEquals(ColorRgb(1f, 0f, 0f), resolved.multiplyColor)
assertEquals(0.25f, resolved.opacity, "an unrelated channel keeps its own value")
}
}
@@ -0,0 +1,63 @@
package org.umamo.render.eval
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
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.PuppetModel
import org.umamo.runtime.model.WarpLatticeForm
import kotlin.test.Test
import kotlin.test.assertEquals
/**
* Assembly tests for [CpuDeformationEvaluator] on tiny synthetic models: that it routes direct vs
* deformer-parented meshes correctly and resolves unspecified parameters to their defaults. The
* per-stage math is covered by the keyform/transform/cascade tests; this checks the wiring.
*/
class CpuDeformationEvaluatorTest {
private val tol = 1e-4f
private val paramA = ParameterId("A")
private fun axis() = listOf(KeyformAxis(paramA, floatArrayOf(0f)))
private fun zeroMeshGrid(coordCount: Int) = KeyformGrid(axis(), listOf(KeyformCell(intArrayOf(0), MeshDeltaForm(FloatArray(coordCount)))))
private fun model(deformers: List<Deformer>, drawable: Drawable) =
PuppetModel(
parameters = listOf(Parameter(paramA, "A", -1f, 1f, 0f)),
parts = emptyList(),
deformers = deformers,
drawables = listOf(drawable),
rootChildren = listOf(OrgChild.Drawable(drawable.id)),
rootPartId = null,
)
@Test
fun routesDirectMeshWithYFlip() {
val mesh = DrawableMesh(floatArrayOf(10f, 5f, 20f, 7f), FloatArray(0), IntArray(0))
val drawable = Drawable(DrawableId("M"), "M", null, BlendMode.Normal, emptyList(), mesh, zeroMeshGrid(4))
val geo = CpuDeformationEvaluator().evaluate(model(emptyList(), drawable), emptyMap())
assertEquals(listOf(10f, -5f, 20f, -7f), geo.worldPositions[DrawableId("M")]!!.toList())
}
@Test
fun routesMeshThroughItsWarpParent() {
val warpCp = floatArrayOf(10f, 20f, 12f, 20f, 10f, 24f, 12f, 24f) // 2×4 rect at (10,20)
val warp = Deformer.Warp(DeformerId("W"), "W", null, null, 1, 1, true, KeyformGrid(axis(), listOf(KeyformCell(intArrayOf(0), WarpLatticeForm(warpCp)))))
val mesh = DrawableMesh(floatArrayOf(0.5f, 0.5f), FloatArray(0), IntArray(0))
val drawable = Drawable(DrawableId("M"), "M", DeformerId("W"), BlendMode.Normal, emptyList(), mesh, zeroMeshGrid(2))
val geo = CpuDeformationEvaluator().evaluate(model(listOf(warp), drawable), emptyMap())
val world = geo.worldPositions[DrawableId("M")]!!
assertEquals(11f, world[0], tol)
assertEquals(-22f, world[1], tol)
}
}
@@ -0,0 +1,91 @@
package org.umamo.render.eval
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertTrue
/**
* Unit tests for the warp (in-grid + extrapolation) and rotation transforms on synthetic lattices.
* The identity unit-square lattice is linear everywhere, so it maps `(u,v)` to `(u,v)` both inside the
* grid and under extrapolation - a clean oracle for the FFD math without the corpus.
*/
class DeformTransformsTest {
private val tol = 1e-4f
// Identity unit-square 1×1 lattice: cp00=(0,0) cp10=(1,0) cp01=(0,1) cp11=(1,1).
private val identity = floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f, 1f, 1f)
@Test
fun identityGridMapsUvToUvBilinear() {
val out = FloatArray(2)
assertTrue(warpInGrid(identity, 1, 1, true, 0.5f, 0.5f, out, 0))
assertEquals(0.5f, out[0], tol)
assertEquals(0.5f, out[1], tol)
warpApply(identity, 1, 1, true, 0.25f, 0.75f, out, 0)
assertEquals(0.25f, out[0], tol)
assertEquals(0.75f, out[1], tol)
}
@Test
fun identityGridMapsUvToUvTriangle() {
val out = FloatArray(2)
warpApply(identity, 1, 1, false, 0.25f, 0.25f, out, 0) // lower triangle (u+v <= 1)
assertEquals(0.25f, out[0], tol)
assertEquals(0.25f, out[1], tol)
warpApply(identity, 1, 1, false, 0.7f, 0.6f, out, 0) // upper triangle (u+v > 1)
assertEquals(0.7f, out[0], tol)
assertEquals(0.6f, out[1], tol)
}
@Test
fun warpReturnsFalseOutsideGrid() {
val out = FloatArray(2)
assertFalse(warpInGrid(identity, 1, 1, true, 1.5f, 0.5f, out, 0))
assertFalse(warpInGrid(identity, 1, 1, true, -0.1f, 0.5f, out, 0))
}
@Test
fun translatedScaledGridMapsCenter() {
// A 1×1 lattice placed as a 2×4 rectangle at (10,20): corners (10,20)(12,20)(10,24)(12,24).
val grid = floatArrayOf(10f, 20f, 12f, 20f, 10f, 24f, 12f, 24f)
val out = FloatArray(2)
warpApply(grid, 1, 1, true, 0.5f, 0.5f, out, 0)
assertEquals(11f, out[0], tol)
assertEquals(22f, out[1], tol)
}
@Test
fun identityGridExtrapolatesLinearly() {
val out = FloatArray(2)
// Far outside -> pure affine; the identity lattice is linear, so (u,v) maps to (u,v).
warpApply(identity, 1, 1, true, 5f, 2f, out, 0)
assertEquals(5f, out[0], tol)
assertEquals(2f, out[1], tol)
warpApply(identity, 1, 1, true, -3f, 4f, out, 0)
assertEquals(-3f, out[0], tol)
assertEquals(4f, out[1], tol)
}
@Test
fun rotation90DegreesRotatesPoint() {
val xform = rotationXform(90f, 1f, false, false, 0f, 0f)
val out = FloatArray(2)
xform.apply(1f, 0f, out, 0) // (1,0) rotated +90 -> (0,1)
assertEquals(0f, out[0], tol)
assertEquals(1f, out[1], tol)
xform.apply(0f, 1f, out, 0) // (0,1) -> (-1,0)
assertEquals(-1f, out[0], tol)
assertEquals(0f, out[1], tol)
}
@Test
fun rotationAppliesScaleFlipOrigin() {
// angle 0, scale 2, flipX, origin (5,-3): x' = -2·x + 5, y' = 2·y - 3.
val xform = rotationXform(0f, 2f, true, false, 5f, -3f)
val out = FloatArray(2)
xform.apply(1f, 1f, out, 0)
assertEquals(3f, out[0], tol)
assertEquals(-1f, out[1], tol)
}
}
@@ -0,0 +1,169 @@
package org.umamo.render.eval
import org.umamo.runtime.keyform.fanOutWarp
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
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.ParameterId
import org.umamo.runtime.model.RotationPivotForm
import org.umamo.runtime.model.WarpForm
import org.umamo.runtime.model.WarpLatticeForm
import kotlin.test.Test
import kotlin.test.assertEquals
/**
* Cascade tests on synthetic single-level and nested hierarchies. A mesh's local verts are pushed
* through its parent deformer's baked world transform and Y-flipped; nesting composes the transforms
* top-down.
*/
class DeformerCascadeTest {
private val tol = 1e-4f
private val paramA = ParameterId("A")
private fun values(vararg pairs: Pair<ParameterId, Float>): (ParameterId) -> Float {
val map = pairs.toMap()
return { map[it] ?: 0f }
}
private fun singleKeyAxis() = listOf(KeyformAxis(paramA, floatArrayOf(0f)))
private fun warp(id: String, parent: String?, cols: Int, rows: Int, bilinear: Boolean, cp: FloatArray): Deformer.Warp {
val grid = KeyformGrid(singleKeyAxis(), listOf(KeyformCell(intArrayOf(0), WarpLatticeForm(cp))))
return Deformer.Warp(DeformerId(id), id, parent?.let(::DeformerId), null, rows, cols, bilinear, grid)
}
private fun rotation(id: String, baseAngle: Float, originX: Float, originY: Float, angle: Float, scale: Float): Deformer.Rotation {
val grid = KeyformGrid(singleKeyAxis(), listOf(KeyformCell(intArrayOf(0), RotationPivotForm(originX, originY, angle, scale))))
return Deformer.Rotation(DeformerId(id), id, null, null, baseAngle, grid)
}
private fun zeroDeltaMesh(vertexCount: Int): KeyformGrid<MeshDeltaForm> =
KeyformGrid(singleKeyAxis(), listOf(KeyformCell(intArrayOf(0), MeshDeltaForm(FloatArray(vertexCount * 2)))))
@Test
fun meshUnderTranslatedWarp() {
// 1×1 lattice placed as a 2×4 rect at (10,20).
val warp = warp("W", null, 1, 1, true, floatArrayOf(10f, 20f, 12f, 20f, 10f, 24f, 12f, 24f))
val parent = buildDeformerWorlds(listOf(warp), values(paramA to 0f))[DeformerId("W")]!!
val world = deformMeshThroughParent(zeroDeltaMesh(1), floatArrayOf(0.5f, 0.5f), parent, values(paramA to 0f))!!
assertEquals(11f, world[0], tol)
assertEquals(-22f, world[1], tol) // center (11,22), Y-flipped
}
@Test
fun meshUnderRootRotation() {
val rotation = rotation("R", 0f, 0f, 0f, 90f, 1f)
val parent = buildDeformerWorlds(listOf(rotation), values(paramA to 0f))[DeformerId("R")]!!
val world = deformMeshThroughParent(zeroDeltaMesh(1), floatArrayOf(1f, 0f), parent, values(paramA to 0f))!!
assertEquals(0f, world[0], tol) // (1,0) rotated +90 -> (0,1)
assertEquals(-1f, world[1], tol) // Y-flipped
}
@Test
fun nestedWarpComposesParentTransform() {
// Parent translates +100 in x; child is identity -> composed lattice is the parent's.
val parentWarp = warp("P", null, 1, 1, true, floatArrayOf(100f, 0f, 101f, 0f, 100f, 1f, 101f, 1f))
val childWarp = warp("C", "P", 1, 1, true, floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f, 1f, 1f))
val worlds = buildDeformerWorlds(listOf(parentWarp, childWarp), values(paramA to 0f))
val child = worlds[DeformerId("C")]!!
val world = deformMeshThroughParent(zeroDeltaMesh(1), floatArrayOf(0.5f, 0.5f), child, values(paramA to 0f))!!
assertEquals(100.5f, world[0], tol) // center of the +100-translated lattice
assertEquals(-0.5f, world[1], tol)
}
// --- Render-channel cascade -------------------------------------------------------------------
// A deformer's opacity and multiply/screen colors apply to every drawable underneath it, composed
// down the chain. Riggers key the opacity as a subtree show/hide switch, so these compositions are
// load-bearing rather than cosmetic.
/** A 1x1 identity-lattice warp carrying render channels, for channel-only assertions. */
private fun channelWarp(
id: String,
parent: String?,
opacity: Float,
multiplyColor: ColorRgb = ColorRgb.MultiplyIdentity,
screenColor: ColorRgb = ColorRgb.ScreenIdentity,
): Deformer.Warp {
// Built bundled and fanned out, so the fixture exercises the real import split rather than
// hand-assembling tracks that could drift from what an importer actually produces.
val form = WarpForm(floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f, 1f, 1f), opacity, multiplyColor, screenColor)
val fanned = KeyformGrid(singleKeyAxis(), listOf(KeyformCell(intArrayOf(0), form))).fanOutWarp()
return Deformer.Warp(DeformerId(id), id, parent?.let(::DeformerId), null, 1, 1, true, fanned.geometry, fanned.channels)
}
@Test
fun rootDeformerChannelsPassThroughUnchanged() {
val root = channelWarp("W", null, 0.5f, ColorRgb(0.25f, 0.5f, 1f), ColorRgb(0.1f, 0f, 0f))
val world = buildDeformerWorlds(listOf(root), values(paramA to 0f))[DeformerId("W")]!!
// Identity parents: multiplying by white and screening with black both return the local value.
assertEquals(0.5f, world.accumulatedOpacity, tol)
assertEquals(0.25f, world.accumulatedMultiplyColor.red, tol)
assertEquals(1f, world.accumulatedMultiplyColor.blue, tol)
assertEquals(0.1f, world.accumulatedScreenColor.red, tol)
}
@Test
fun nestedDeformerOpacityMultipliesDownTheChain() {
val parent = channelWarp("P", null, 0.5f)
val child = channelWarp("C", "P", 0.5f)
val worlds = buildDeformerWorlds(listOf(parent, child), values(paramA to 0f))
assertEquals(0.5f, worlds[DeformerId("P")]!!.accumulatedOpacity, tol)
assertEquals(0.25f, worlds[DeformerId("C")]!!.accumulatedOpacity, tol) // 0.5 * 0.5
}
@Test
fun nestedMultiplyColorComposesComponentwise() {
val parent = channelWarp("P", null, 1f, multiplyColor = ColorRgb(0.5f, 1f, 0.25f))
val child = channelWarp("C", "P", 1f, multiplyColor = ColorRgb(0.5f, 0.5f, 1f))
val accumulated = buildDeformerWorlds(listOf(parent, child), values(paramA to 0f))[DeformerId("C")]!!
assertEquals(0.25f, accumulated.accumulatedMultiplyColor.red, tol) // 0.5 * 0.5
assertEquals(0.5f, accumulated.accumulatedMultiplyColor.green, tol) // 0.5 * 1
assertEquals(0.25f, accumulated.accumulatedMultiplyColor.blue, tol) // 1 * 0.25
}
@Test
fun nestedScreenColorComposesWithTheScreenOperator() {
// Screen is a + b - a*b, NOT a product: two half-screens make 0.75, not 0.25.
val parent = channelWarp("P", null, 1f, screenColor = ColorRgb(0.5f, 0f, 1f))
val child = channelWarp("C", "P", 1f, screenColor = ColorRgb(0.5f, 0.25f, 0.5f))
val accumulated = buildDeformerWorlds(listOf(parent, child), values(paramA to 0f))[DeformerId("C")]!!
assertEquals(0.75f, accumulated.accumulatedScreenColor.red, tol) // 0.5+0.5-0.25
assertEquals(0.25f, accumulated.accumulatedScreenColor.green, tol) // 0.25+0-0
assertEquals(1f, accumulated.accumulatedScreenColor.blue, tol) // screening with white saturates
}
@Test
fun identityChannelsLeaveADeepChainUntouched() {
// The common case: nothing authored, so a three-deep chain must not drift off the identities.
val worlds =
buildDeformerWorlds(
listOf(channelWarp("A", null, 1f), channelWarp("B", "A", 1f), channelWarp("C", "B", 1f)),
values(paramA to 0f),
)
val deepest = worlds[DeformerId("C")]!!
assertEquals(1f, deepest.accumulatedOpacity, tol)
assertEquals(ColorRgb.MultiplyIdentity, deepest.accumulatedMultiplyColor)
assertEquals(ColorRgb.ScreenIdentity, deepest.accumulatedScreenColor)
}
@Test
fun channelsBlendAcrossKeysRatherThanSnapping() {
// A two-key axis keyed 1 -> 0: at the midpoint the subtree must be half faded, not fully on or
// fully off. Snapping to the nearest key was a real bug in the reference implementation.
val fanned =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0f, 1f))),
listOf(
KeyformCell(intArrayOf(0), WarpForm(floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f, 1f, 1f), 1f)),
KeyformCell(intArrayOf(1), WarpForm(floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f, 1f, 1f), 0f)),
),
).fanOutWarp()
val fading = Deformer.Warp(DeformerId("F"), "F", null, null, 1, 1, true, fanned.geometry, fanned.channels)
val atMidpoint = buildDeformerWorlds(listOf(fading), values(paramA to 0.5f))[DeformerId("F")]!!
assertEquals(0.5f, atMidpoint.accumulatedOpacity, tol)
}
}
@@ -0,0 +1,345 @@
package org.umamo.render.eval
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
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.Parameter
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RotationPivotForm
import org.umamo.runtime.model.WarpLatticeForm
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Verifies [DrawableSpaceMapping]: the forward local->world projection matches the evaluator's world
* positions exactly (same chain, same Y negation), and the inverse recovers local coordinates - in
* closed form for rotation parents, by Newton iteration for warp parents - including for a moved
* world target (the Edit-gizmo drag case). Degenerate transforms keep the seed instead of exploding.
* The single-step [DrawableSpaceMapping.worldToLocalLinearized] used by the transform path is exact for
* affine parents and, unlike the Newton inverse, follows a large warp-child drag without pinning or
* boiling.
*/
class DrawableSpaceMappingTest {
private val tol = 1e-3f
private val paramA = ParameterId("A")
private val drawableId = DrawableId("M")
private fun axis() = listOf(KeyformAxis(paramA, floatArrayOf(0f)))
private fun zeroMeshGrid(coordCount: Int) = KeyformGrid(axis(), listOf(KeyformCell(intArrayOf(0), MeshDeltaForm(FloatArray(coordCount)))))
private fun drawable(parent: DeformerId?, positions: FloatArray) =
Drawable(drawableId, "M", parent, BlendMode.Normal, emptyList(), DrawableMesh(positions, FloatArray(0), IntArray(0)), zeroMeshGrid(positions.size))
private fun model(deformers: List<Deformer>, drawable: Drawable) =
PuppetModel(listOf(Parameter(paramA, "A", -1f, 1f, 0f)), emptyList(), deformers, listOf(drawable), emptyList(), null)
/** 2x4 world rectangle at (10,20): the same 1x1 quad lattice the evaluator's warp routing test uses. */
private fun warpDeformer(): Deformer.Warp {
val controlPoints = floatArrayOf(10f, 20f, 12f, 20f, 10f, 24f, 12f, 24f)
return Deformer.Warp(DeformerId("W"), "W", null, null, 1, 1, true, KeyformGrid(axis(), listOf(KeyformCell(intArrayOf(0), WarpLatticeForm(controlPoints)))))
}
/** Rotation about (5,5): 90 degrees, scale 2, no flips. */
private fun rotationDeformer(scale: Float = 2f) =
Deformer.Rotation(
DeformerId("R"),
"R",
null,
null,
0f,
KeyformGrid(axis(), listOf(KeyformCell(intArrayOf(0), RotationPivotForm(5f, 5f, 90f, scale)))),
)
/** A direct (deformer-less) drawable maps by pure Y negation, and the inverse recovers it exactly. */
@Test
fun directDrawableIsPureYNegate() {
val local = floatArrayOf(10f, 5f, 20f, 7f)
val mapping = assertNotNull(drawableSpaceMapping(model(emptyList(), drawable(null, local)), emptyMap(), drawableId))
val world = mapping.localToWorld(local)
assertEquals(listOf(10f, -5f, 20f, -7f), world.toList())
val recovered = mapping.worldToLocal(world, FloatArray(local.size), setOf(0, 1))
assertEquals(local.toList(), recovered.toList())
}
/** A warp child's forward projection matches the evaluator, and Newton recovers the seed UV. */
@Test
fun warpChildMatchesEvaluatorAndRoundTrips() {
val local = floatArrayOf(0.5f, 0.5f)
val puppet = model(listOf(warpDeformer()), drawable(DeformerId("W"), local))
val mapping = assertNotNull(drawableSpaceMapping(puppet, emptyMap(), drawableId))
val world = mapping.localToWorld(local)
val evaluatorWorld = CpuDeformationEvaluator().evaluate(puppet, emptyMap()).worldPositions.getValue(drawableId)
assertEquals(evaluatorWorld[0], world[0], tol, "forward x matches the evaluator")
assertEquals(evaluatorWorld[1], world[1], tol, "forward y matches the evaluator")
val recovered = mapping.worldToLocal(world, local, setOf(0))
assertEquals(0.5f, recovered[0], 1e-4f, "u round-trips")
assertEquals(0.5f, recovered[1], 1e-4f, "v round-trips")
}
/** The drag case: inverting a MOVED world target yields a UV whose forward projection hits it. */
@Test
fun warpInverseSolvesAMovedTarget() {
val local = floatArrayOf(0.5f, 0.5f)
val puppet = model(listOf(warpDeformer()), drawable(DeformerId("W"), local))
val mapping = assertNotNull(drawableSpaceMapping(puppet, emptyMap(), drawableId))
val movedWorld = mapping.localToWorld(local)
movedWorld[0] += 0.5f
movedWorld[1] -= 0.9f
val solvedLocal = mapping.worldToLocal(movedWorld, local, setOf(0))
val reprojected = mapping.localToWorld(solvedLocal)
assertEquals(movedWorld[0], reprojected[0], tol, "reprojected x hits the moved target")
assertEquals(movedWorld[1], reprojected[1], tol, "reprojected y hits the moved target")
}
/** A rotation child's forward projection matches the evaluator; the closed-form inverse recovers it. */
@Test
fun rotationChildMatchesEvaluatorAndRoundTrips() {
val local = floatArrayOf(1f, 0f, 0f, 3f)
val puppet = model(listOf(rotationDeformer()), drawable(DeformerId("R"), local))
val mapping = assertNotNull(drawableSpaceMapping(puppet, emptyMap(), drawableId))
val world = mapping.localToWorld(local)
val evaluatorWorld = CpuDeformationEvaluator().evaluate(puppet, emptyMap()).worldPositions.getValue(drawableId)
for (coordIndex in world.indices) {
assertEquals(evaluatorWorld[coordIndex], world[coordIndex], tol, "forward coord $coordIndex matches the evaluator")
}
val recovered = mapping.worldToLocal(world, FloatArray(local.size), setOf(0, 1))
for (coordIndex in local.indices) {
assertEquals(local[coordIndex], recovered[coordIndex], tol, "inverse coord $coordIndex round-trips")
}
}
/** A zero-scale rotation has no inverse: the seed is kept untouched and nothing goes NaN. */
@Test
fun degenerateRotationKeepsSeed() {
val local = floatArrayOf(1f, 0f)
val puppet = model(listOf(rotationDeformer(scale = 0f)), drawable(DeformerId("R"), local))
val mapping = assertNotNull(drawableSpaceMapping(puppet, emptyMap(), drawableId))
val world = mapping.localToWorld(local)
val recovered = mapping.worldToLocal(world, local, setOf(0))
assertEquals(local.toList(), recovered.toList(), "seed kept")
assertFalse(recovered.any { it.isNaN() }, "no NaN")
}
/** drawableLocalPosed blends base + keyform deltas exactly like the renderer's local stage. */
@Test
fun drawableLocalPosedBlendsBetweenKeys() {
val blendGrid =
KeyformGrid(
axes = listOf(KeyformAxis(paramA, floatArrayOf(0f, 10f))),
cells =
listOf(
KeyformCell(intArrayOf(0), MeshDeltaForm(floatArrayOf(0f, 0f))),
KeyformCell(intArrayOf(1), MeshDeltaForm(floatArrayOf(4f, 0f))),
),
)
val blendDrawable =
Drawable(drawableId, "M", null, BlendMode.Normal, emptyList(), DrawableMesh(floatArrayOf(1f, 2f), FloatArray(0), IntArray(0)), blendGrid)
val puppet = PuppetModel(listOf(Parameter(paramA, "A", 0f, 10f, 0f)), emptyList(), emptyList(), listOf(blendDrawable), emptyList(), null)
val halfway = assertNotNull(drawableLocalPosed(puppet, mapOf(paramA to 5f), drawableId))
assertEquals(3f, halfway[0], tol, "base 1 + half of delta 4")
assertEquals(2f, halfway[1], tol, "y unchanged")
assertNull(drawableLocalPosed(puppet, emptyMap(), DrawableId("absent")), "missing drawable")
}
/** No such drawable, or a parent whose world cannot be built, cannot be mapped. */
@Test
fun unmappableCasesReturnNull() {
val puppet = model(emptyList(), drawable(DeformerId("missing"), floatArrayOf(0f, 0f)))
assertNull(drawableSpaceMapping(puppet, emptyMap(), DrawableId("absent")), "missing drawable")
assertNull(drawableSpaceMapping(puppet, emptyMap(), drawableId), "unbuildable parent world")
}
/**
* A warp-child grab far past the lattice follows the cursor with the linearized inverse, where the
* damped iterative [DrawableSpaceMapping.worldToLocal] pins short of the target: the 2x4 cage spans 2
* world-x per lattice UV, so its damped ~10-UV Newton reach stalls near world-x 31, and a +200 grab
* targets far beyond that reach.
*/
@Test
fun warpLargeGrabFollowsInsteadOfPinning() {
val local = floatArrayOf(0.5f, 0.5f)
val puppet = model(listOf(warpDeformer()), drawable(DeformerId("W"), local))
val mapping = assertNotNull(drawableSpaceMapping(puppet, emptyMap(), drawableId))
val worldRest = mapping.localToWorld(local)
val worldTarget = worldRest.copyOf().also { it[0] += 200f }
// The linearized inverse follows the 200-unit grab to within a world unit (the residual is
// finite-difference Jacobian error, not the Newton reach cliff). A true inverse would be exact, but
// sub-unit accuracy on a 200-unit drag is visually indistinguishable and never pins.
val solvedLinearized = mapping.worldToLocalLinearized(worldTarget, local, worldRest, setOf(0))
val reprojectedLinearized = mapping.localToWorld(solvedLinearized)
val linearizedShortfall = abs(reprojectedLinearized[0] - worldTarget[0])
assertTrue(linearizedShortfall < 1f, "linearized inverse follows the cursor (shortfall=$linearizedShortfall)")
assertEquals(worldTarget[1], reprojectedLinearized[1], tol, "no drift on the unmoved axis")
// Regression guard: the damped iterative inverse pins well short of the target.
val solvedNewton = mapping.worldToLocal(worldTarget, local, setOf(0))
val reprojectedNewton = mapping.localToWorld(solvedNewton)
assertTrue(abs(reprojectedNewton[0] - worldTarget[0]) > 100f, "the Newton inverse pins at its reach limit")
}
/**
* A swept warp-child grab follows the cursor without pinning or boiling. The reach-uncapped per-vertex
* inverse lands the vertex on the moving target every frame (it reprojects onto it - never pins short),
* and the solved local coordinate advances in bounded steps (no jitter / scatter), even as the sweep
* crosses the piecewise extrapolation band where the reach-capped inverse was noisy.
*/
@Test
fun warpSweptGrabIsContinuousNoBoil() {
val controlPoints = floatArrayOf(0f, 0f, 10f, 0f, 0f, 10f, 14f, 12f)
val warp = Deformer.Warp(DeformerId("W"), "W", null, null, 1, 1, true, KeyformGrid(axis(), listOf(KeyformCell(intArrayOf(0), WarpLatticeForm(controlPoints)))))
val local = floatArrayOf(0.5f, 0.5f)
val mapping = assertNotNull(drawableSpaceMapping(model(listOf(warp), drawable(DeformerId("W"), local)), emptyMap(), drawableId))
val worldRest = mapping.localToWorld(local)
var previousLocalU = Float.NaN
for (frame in 1..200) {
val worldTarget =
worldRest.copyOf().also {
it[0] += frame * 3f
it[1] -= frame * 2f
}
val solved = mapping.worldToLocalLinearized(worldTarget, local, worldRest, setOf(0))
val reprojected = mapping.localToWorld(solved)
// Follows: the reach-uncapped inverse lands the vertex on the moving target (never pins).
assertEquals(worldTarget[0], reprojected[0], 1f, "swept grab follows the target x (frame $frame)")
assertEquals(worldTarget[1], reprojected[1], 1f, "swept grab follows the target y (frame $frame)")
if (!previousLocalU.isNaN()) {
// No boil: the solved coordinate advances in a bounded step, never jittering / scattering.
assertTrue(abs(solved[0] - previousLocalU) < 1f, "solved u advances smoothly, no boil (frame $frame)")
}
previousLocalU = solved[0]
}
}
/** The linearized inverse is exact for affine parents (direct and rotation) and agrees with the closed form. */
@Test
fun linearizedIsExactForAffineParents() {
val directLocal = floatArrayOf(10f, 5f, 20f, 7f)
val directMapping = assertNotNull(drawableSpaceMapping(model(emptyList(), drawable(null, directLocal)), emptyMap(), drawableId))
val directRest = directMapping.localToWorld(directLocal)
val directTarget =
directRest.copyOf().also {
it[0] += 3f
it[1] += 4f
it[2] -= 5f
it[3] += 6f
}
val directSolved = directMapping.worldToLocalLinearized(directTarget, directLocal, directRest, setOf(0, 1))
val directReprojected = directMapping.localToWorld(directSolved)
for (coordIndex in directTarget.indices) {
assertEquals(directTarget[coordIndex], directReprojected[coordIndex], tol, "direct reprojects onto target")
}
val directClosed = directMapping.worldToLocal(directTarget, directLocal, setOf(0, 1))
for (coordIndex in directSolved.indices) {
assertEquals(directClosed[coordIndex], directSolved[coordIndex], tol, "direct agrees with the closed form")
}
val rotationLocal = floatArrayOf(1f, 0f, 0f, 3f)
val rotationMapping = assertNotNull(drawableSpaceMapping(model(listOf(rotationDeformer()), drawable(DeformerId("R"), rotationLocal)), emptyMap(), drawableId))
val rotationRest = rotationMapping.localToWorld(rotationLocal)
val rotationTarget =
rotationRest.copyOf().also {
it[0] += 40f
it[1] -= 25f
}
val rotationSolved = rotationMapping.worldToLocalLinearized(rotationTarget, rotationLocal, rotationRest, setOf(0))
val rotationReprojected = rotationMapping.localToWorld(rotationSolved)
assertEquals(rotationTarget[0], rotationReprojected[0], tol, "rotation reprojects onto target")
assertEquals(rotationTarget[1], rotationReprojected[1], tol, "rotation reprojects onto target")
assertEquals(rotationLocal[2], rotationSolved[2], tol, "untouched vertex kept")
assertEquals(rotationLocal[3], rotationSolved[3], tol, "untouched vertex kept")
}
/**
* A warp-child Grab is world-rigid: the per-vertex exact inverse lands every vertex on its own world
* target, so the mesh translates as a rigid body in world space with no squish at all - the property
* the shared-Jacobian linearizations cannot hold on a curved cage.
*/
@Test
fun warpGrabIsWorldRigid() {
// A non-parallelogram cage so the warp Jacobian genuinely varies across the lattice.
val controlPoints = floatArrayOf(0f, 0f, 10f, 0f, 0f, 10f, 14f, 12f)
val warp = Deformer.Warp(DeformerId("W"), "W", null, null, 1, 1, true, KeyformGrid(axis(), listOf(KeyformCell(intArrayOf(0), WarpLatticeForm(controlPoints)))))
val local = floatArrayOf(0.3f, 0.3f, 0.7f, 0.6f)
val mapping = assertNotNull(drawableSpaceMapping(model(listOf(warp), drawable(DeformerId("W"), local)), emptyMap(), drawableId))
val worldRest = mapping.localToWorld(local)
// One shared world delta on both vertices (a Grab).
val worldTarget =
worldRest.copyOf().also {
it[0] += 8f
it[1] -= 5f
it[2] += 8f
it[3] -= 5f
}
val solved = mapping.worldToLocalLinearized(worldTarget, local, worldRest, setOf(0, 1))
val reprojected = mapping.localToWorld(solved)
for (coordIndex in worldTarget.indices) {
assertEquals(worldTarget[coordIndex], reprojected[coordIndex], tol, "vertex reprojects exactly onto its world target (coord $coordIndex)")
}
}
/**
* On a strongly curved cage - the real-model failure (three nested, upward-bowed warps) in miniature -
* a large multi-vertex grab lands the selection's centroid on the cursor. The world-rigid inverse lands
* every vertex on target, so the centroid trivially follows too (the shared-Jacobian inverses miss here).
*/
@Test
fun warpCurvedCageGrabLandsCentroidOnTarget() {
// A 2x1 cage bowed upward in the middle column, so the local->world scale varies sharply across it.
val controlPoints = floatArrayOf(0f, 0f, 10f, -4f, 20f, 0f, 0f, 10f, 10f, 6f, 20f, 10f)
val warp = Deformer.Warp(DeformerId("W"), "W", null, null, 1, 2, true, KeyformGrid(axis(), listOf(KeyformCell(intArrayOf(0), WarpLatticeForm(controlPoints)))))
val local = floatArrayOf(0.2f, 0.4f, 0.5f, 0.3f, 0.8f, 0.4f, 0.5f, 0.7f)
val indices = setOf(0, 1, 2, 3)
val mapping = assertNotNull(drawableSpaceMapping(model(listOf(warp), drawable(DeformerId("W"), local)), emptyMap(), drawableId))
val worldRest = mapping.localToWorld(local)
// A large grab: shift every vertex by the same world delta, far past the cage.
val worldTarget = worldRest.copyOf()
for (vertexIndex in 0 until 4) {
worldTarget[vertexIndex * 2] += 60f
worldTarget[vertexIndex * 2 + 1] += 40f
}
val solved = mapping.worldToLocalLinearized(worldTarget, local, worldRest, indices)
// Reproject the solved centroid and compare to the target centroid: the gross offset is gone.
var centroidU = 0f
var centroidV = 0f
for (vertexIndex in 0 until 4) {
centroidU += solved[vertexIndex * 2]
centroidV += solved[vertexIndex * 2 + 1]
}
val reprojectedCentroid = mapping.localToWorld(floatArrayOf(centroidU / 4f, centroidV / 4f))
val targetCentroidX = (worldTarget[0] + worldTarget[2] + worldTarget[4] + worldTarget[6]) / 4f
val targetCentroidY = (worldTarget[1] + worldTarget[3] + worldTarget[5] + worldTarget[7]) / 4f
assertEquals(targetCentroidX, reprojectedCentroid[0], 1f, "grabbed centroid lands on the cursor x")
assertEquals(targetCentroidY, reprojectedCentroid[1], 1f, "grabbed centroid lands on the cursor y")
}
/** A zero-scale (degenerate) rotation parent keeps the seed in the linearized inverse; nothing goes NaN. */
@Test
fun linearizedDegenerateRotationKeepsSeed() {
val local = floatArrayOf(1f, 0f)
val puppet = model(listOf(rotationDeformer(scale = 0f)), drawable(DeformerId("R"), local))
val mapping = assertNotNull(drawableSpaceMapping(puppet, emptyMap(), drawableId))
val worldRest = mapping.localToWorld(local)
val worldTarget = worldRest.copyOf().also { it[0] += 9f }
val solved = mapping.worldToLocalLinearized(worldTarget, local, worldRest, setOf(0))
assertEquals(local.toList(), solved.toList(), "seed kept")
assertFalse(solved.any { it.isNaN() }, "no NaN")
}
}
@@ -0,0 +1,91 @@
package org.umamo.render.eval
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.Glue
import org.umamo.runtime.model.GluePair
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.PuppetModel
import kotlin.test.Test
import kotlin.test.assertEquals
/**
* Verifies the glue weld ([applyGluesResolved]): each pair slides `A' = A + (B−A)·wA`, `B' = B + (A−B)·wB`
* from the pre-blend positions. When `wA + wB = 1` (the editor's case) the two converge to one point.
*/
class GlueTest {
/** A direct (deformer-less) one-vertex drawable resting at `(x, y)` - evaluates to world `(x, −y)`. */
private fun pointDrawable(raw: String, x: Float, y: Float): Drawable {
val grid = KeyformGrid(emptyList<KeyformAxis>(), listOf(KeyformCell(intArrayOf(), MeshDeltaForm(floatArrayOf(0f, 0f)))))
return Drawable(
id = DrawableId(raw),
name = raw,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(floatArrayOf(x, y), floatArrayOf(0f, 0f), IntArray(0)),
geometryGrid = grid,
)
}
private fun modelWith(a: Drawable, b: Drawable, glue: Glue) =
PuppetModel(
parameters = emptyList(),
parts = emptyList(),
deformers = emptyList(),
drawables = listOf(a, b),
rootChildren = listOf(OrgChild.Drawable(a.id), OrgChild.Drawable(b.id)),
rootPartId = null,
glues = listOf(glue),
)
@Test
fun equalWeightsWeldToMidpoint() {
val model =
modelWith(
pointDrawable("A", 10f, 0f),
pointDrawable("B", 20f, 0f),
Glue(DrawableId("A"), DrawableId("B"), listOf(GluePair(0, 0, 0.5f, 0.5f))),
)
val geometry = CpuDeformationEvaluator().evaluate(model, emptyMap())
assertEquals(15f, geometry.worldPositions.getValue(DrawableId("A"))[0], 1e-4f)
assertEquals(15f, geometry.worldPositions.getValue(DrawableId("B"))[0], 1e-4f)
}
@Test
fun complementaryWeightsConvergeToOnePoint() {
// wA + wB = 1 (the editor's seam case): A' and B' land on the exact same point.
val model =
modelWith(
pointDrawable("A", 10f, 4f),
pointDrawable("B", 22f, -8f),
Glue(DrawableId("A"), DrawableId("B"), listOf(GluePair(0, 0, 0.25f, 0.75f))),
)
val geometry = CpuDeformationEvaluator().evaluate(model, emptyMap())
val a = geometry.worldPositions.getValue(DrawableId("A"))
val b = geometry.worldPositions.getValue(DrawableId("B"))
assertEquals(a[0], b[0], 1e-4f)
assertEquals(a[1], b[1], 1e-4f)
assertEquals(13f, a[0], 1e-4f) // 10 + (22−10)·0.25
}
@Test
fun fullWeightSnapsOneSideOnly() {
// wA = 1 → A snaps onto B; wB = 0 → B stays put.
val model =
modelWith(
pointDrawable("A", 10f, 0f),
pointDrawable("B", 20f, 0f),
Glue(DrawableId("A"), DrawableId("B"), listOf(GluePair(0, 0, 1f, 0f))),
)
val geometry = CpuDeformationEvaluator().evaluate(model, emptyMap())
assertEquals(20f, geometry.worldPositions.getValue(DrawableId("A"))[0], 1e-4f)
assertEquals(20f, geometry.worldPositions.getValue(DrawableId("B"))[0], 1e-4f)
}
}
@@ -0,0 +1,21 @@
package org.umamo.render.eval
import org.umamo.runtime.model.Keyform
import kotlin.test.Test
import kotlin.test.assertEquals
class KeyformBlendTest {
@Test
fun blendSumsWeightedDeltas() {
// base + 0.5*[2,4] + 1.0*[1,1] = [1+1+1, 1+2+1] = [3, 4]
val base = floatArrayOf(1f, 1f)
val keyforms =
listOf(
0.5f to Keyform(atValue = 0f, delta = floatArrayOf(2f, 4f)),
1.0f to Keyform(atValue = 1f, delta = floatArrayOf(1f, 1f)),
)
val out = blend(base, keyforms)
assertEquals(3f, out[0])
assertEquals(4f, out[1])
}
}
@@ -0,0 +1,96 @@
package org.umamo.render.eval
import org.umamo.runtime.eval.gridCorners
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.ParameterId
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNull
/**
* Unit tests for the multilinear keyform blend on synthetic grids (no corpus): the snap/interpolate/
* N-D/out-of-range behaviour of [gridCorners] and the cell reproduction of [sampleMeshLocal].
*/
class KeyformGridEvalTest {
private val paramA = ParameterId("A")
private val paramB = ParameterId("B")
private fun values(vararg pairs: Pair<ParameterId, Float>): (ParameterId) -> Float {
val map = pairs.toMap()
return { map[it] ?: 0f }
}
@Test
fun snapsToTheNearestKey() {
val grid = KeyformGrid<MeshDeltaForm>(listOf(KeyformAxis(paramA, floatArrayOf(-1f, 0f, 1f))), emptyList())
val corners = gridCorners(grid, values(paramA to 0f))!!
assertEquals(1, corners.size)
assertEquals(1, corners[0].linearIndex) // the middle key
assertEquals(1f, corners[0].weight)
}
@Test
fun interpolatesBetweenTwoKeys() {
val grid = KeyformGrid<MeshDeltaForm>(listOf(KeyformAxis(paramA, floatArrayOf(-1f, 0f, 1f))), emptyList())
val corners = gridCorners(grid, values(paramA to 0.5f))!!.sortedBy { it.linearIndex }
assertEquals(2, corners.size)
assertEquals(1, corners[0].linearIndex)
assertEquals(2, corners[1].linearIndex)
assertEquals(0.5f, corners[0].weight)
assertEquals(0.5f, corners[1].weight)
}
@Test
fun foldsTwoAxesIntoFourWeightedCorners() {
val axes = listOf(KeyformAxis(paramA, floatArrayOf(-1f, 0f, 1f)), KeyformAxis(paramB, floatArrayOf(-1f, 0f, 1f)))
val grid = KeyformGrid<MeshDeltaForm>(axes, emptyList())
val corners = gridCorners(grid, values(paramA to 0.5f, paramB to 0.5f))!!
assertEquals(4, corners.size)
corners.forEach { assertEquals(0.25f, it.weight) }
// coord (a,b) folds to a + b*3: the four cells surrounding (0.5, 0.5) are (1,1)(2,1)(1,2)(2,2).
assertEquals(setOf(4, 5, 7, 8), corners.map { it.linearIndex }.toSet())
assertEquals(1f, corners.fold(0f) { acc, c -> acc + c.weight })
}
@Test
fun hidesWhenAParameterIsOutOfRange() {
val grid = KeyformGrid<MeshDeltaForm>(listOf(KeyformAxis(paramA, floatArrayOf(-1f, 0f, 1f))), emptyList())
assertNull(gridCorners(grid, values(paramA to -2f)))
}
@Test
fun reproducesAndInterpolatesCellForms() {
val cell0 = KeyformCell(intArrayOf(0), MeshDeltaForm(floatArrayOf(10f, 0f)))
val cell1 = KeyformCell(intArrayOf(1), MeshDeltaForm(floatArrayOf(20f, 0f)))
val cell2 = KeyformCell(intArrayOf(2), MeshDeltaForm(floatArrayOf(30f, 0f)))
val grid = KeyformGrid(listOf(KeyformAxis(paramA, floatArrayOf(-1f, 0f, 1f))), listOf(cell0, cell1, cell2))
val base = floatArrayOf(0f, 0f)
// At an exact key the output equals that cell's absolute form (base + delta).
assertEquals(listOf(10f, 0f), sampleMeshLocal(grid, base, values(paramA to -1f))!!.toList())
assertEquals(listOf(30f, 0f), sampleMeshLocal(grid, base, values(paramA to 1f))!!.toList())
// Midway, the linear blend of the two bracketing forms.
assertEquals(listOf(25f, 0f), sampleMeshLocal(grid, base, values(paramA to 0.5f))!!.toList())
}
@Test
fun directMeshBlendsThenNegatesY() {
val cell0 = KeyformCell(intArrayOf(0), MeshDeltaForm(floatArrayOf(10f, 5f)))
val cell1 = KeyformCell(intArrayOf(1), MeshDeltaForm(floatArrayOf(20f, 7f)))
val grid = KeyformGrid(listOf(KeyformAxis(paramA, floatArrayOf(-1f, 1f))), listOf(cell0, cell1))
val base = floatArrayOf(0f, 0f)
// At a key: world = (formX, -formY) - only Y flips.
assertEquals(listOf(10f, -5f), evalDirectMeshWorld(grid, base, values(paramA to -1f))!!.toList())
// Midway: blend (x=15, y=6) then negate Y -> (15, -6).
assertEquals(listOf(15f, -6f), evalDirectMeshWorld(grid, base, values(paramA to 0f))!!.toList())
}
@Test
fun directMeshHiddenWhenOutOfRange() {
val cell = KeyformCell(intArrayOf(0), MeshDeltaForm(floatArrayOf(10f, 5f)))
val grid = KeyformGrid(listOf(KeyformAxis(paramA, floatArrayOf(-1f, 1f))), listOf(cell))
assertNull(evalDirectMeshWorld(grid, floatArrayOf(0f, 0f), values(paramA to 5f)))
}
}
@@ -0,0 +1,295 @@
package org.umamo.render.eval
import org.umamo.runtime.eval.colorAt
import org.umamo.runtime.eval.scalarAt
import org.umamo.runtime.eval.scalarOrNull
import org.umamo.runtime.keyform.fanOutMesh
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.KeyformAxis
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartComposite
import org.umamo.runtime.model.PartGroupMode
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.withDerivedRenderRoot
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Pins the isolated part channel eval on synthetic tracks: the per-channel multilinear blend, the
* out-of-range fallback to the owner's statics, and [preparePose]'s aggregation into
* [PoseDeformInputs.partCompositeStates].
*/
class PartCompositeEvalTest {
private val paramA = ParameterId("A")
private fun values(vararg pairs: Pair<ParameterId, Float>): (ParameterId) -> Float {
val map = pairs.toMap()
return { map[it] ?: 0f }
}
/** A two-key scalar track on paramA. */
private fun scalarTrack(low: Float, high: Float): KeyformGrid<ChannelValue> =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0f, 1f))),
listOf(
KeyformCell<ChannelValue>(intArrayOf(0), ChannelValue.Scalar(low)),
KeyformCell<ChannelValue>(intArrayOf(1), ChannelValue.Scalar(high)),
),
)
/** A two-key color track on paramA. */
private fun colorTrack(low: ColorRgb, high: ColorRgb): KeyformGrid<ChannelValue> =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0f, 1f))),
listOf(
KeyformCell<ChannelValue>(intArrayOf(0), ChannelValue.Color(low)),
KeyformCell<ChannelValue>(intArrayOf(1), ChannelValue.Color(high)),
),
)
/** The composite channels as independent tracks - what one bundled part grid fans out into. */
private fun compositeChannels(): ChannelGrids =
ChannelGrids(
mapOf(
FormChannel.DRAW_ORDER to scalarTrack(500f, 500f),
FormChannel.OPACITY to scalarTrack(1f, 0.5f),
FormChannel.MULTIPLY_COLOR to colorTrack(ColorRgb(1f, 1f, 1f), ColorRgb(0f, 0.5f, 1f)),
FormChannel.SCREEN_COLOR to colorTrack(ColorRgb(0f, 0f, 0f), ColorRgb(1f, 0.5f, 0f)),
),
)
private val staticComposite =
PartComposite(
opacity = 0.3f,
multiplyColor = ColorRgb(0.1f, 0.2f, 0.3f),
screenColor = ColorRgb(0.4f, 0.5f, 0.6f),
)
@Test
fun blendsEveryChannelWithTheGridWeights() {
val channels = compositeChannels()
val pose = values(paramA to 0.5f)
assertEquals(0.75f, channels.scalarAt(FormChannel.OPACITY, staticComposite.opacity, pose), "opacity midpoint")
assertEquals(
ColorRgb(0.5f, 0.75f, 1f),
channels.colorAt(FormChannel.MULTIPLY_COLOR, staticComposite.multiplyColor, pose),
"multiply midpoint",
)
assertEquals(
ColorRgb(0.5f, 0.25f, 0f),
channels.colorAt(FormChannel.SCREEN_COLOR, staticComposite.screenColor, pose),
"screen midpoint",
)
}
@Test
fun snapsToAKeyExactly() {
val channels = compositeChannels()
val pose = values(paramA to 1f)
assertEquals(0.5f, channels.scalarAt(FormChannel.OPACITY, staticComposite.opacity, pose))
assertEquals(ColorRgb(0f, 0.5f, 1f), channels.colorAt(FormChannel.MULTIPLY_COLOR, staticComposite.multiplyColor, pose))
assertEquals(ColorRgb(1f, 0.5f, 0f), channels.colorAt(FormChannel.SCREEN_COLOR, staticComposite.screenColor, pose))
}
/**
* Out of range a channel falls back to its owner's static value and NEVER hides. Hiding is the
* geometry grid's decision alone - a part has no geometry, and making a keyed opacity able to hide art
* would turn keying opacity on a narrow parameter into a disappearing act at the slider's ends.
*/
@Test
fun outOfRangeChannelsFallBackToTheirStatics() {
val channels = compositeChannels()
val pose = values(paramA to -1f)
assertEquals(staticComposite.opacity, channels.scalarAt(FormChannel.OPACITY, staticComposite.opacity, pose))
assertEquals(staticComposite.multiplyColor, channels.colorAt(FormChannel.MULTIPLY_COLOR, staticComposite.multiplyColor, pose))
// The nullable read still reports absence, which is what keeps the part draw-order map sparse.
assertNull(channels.scalarOrNull(FormChannel.DRAW_ORDER, pose))
}
private fun modelWithIsolatedPart(channelGrids: ChannelGrids): PuppetModel {
val part =
Part(
id = PartId("fx"),
name = "fx",
children = emptyList(),
groupMode = PartGroupMode.Isolated,
composite = staticComposite,
channelGrids = channelGrids,
)
return PuppetModel(
parameters = listOf(Parameter(paramA, "A", -1f, 1f, 0f)),
parts = listOf(part),
deformers = emptyList(),
drawables = emptyList(),
rootChildren = listOf(OrgChild.Part(part.id)),
rootPartId = null,
canvasWidth = 0f,
canvasHeight = 0f,
worldOriginX = 0f,
worldOriginZ = 0f,
).withDerivedRenderRoot()
}
@Test
fun preparePoseBlendsAGriddedIsolatedPart() {
val inputs = preparePose(modelWithIsolatedPart(compositeChannels()), mapOf(paramA to 0.5f))
val state = assertNotNull(inputs.partCompositeStates[PartId("fx")], "isolated part carries a state")
assertEquals(0.75f, state.opacity)
assertEquals(ColorRgb(0.5f, 0.75f, 1f), state.multiplyColor)
}
@Test
fun preparePoseFallsBackToStaticChannelsWithoutAGrid() {
val inputs = preparePose(modelWithIsolatedPart(ChannelGrids.Empty), emptyMap())
val state = assertNotNull(inputs.partCompositeStates[PartId("fx")])
assertEquals(0.3f, state.opacity, "PartComposite static opacity")
assertEquals(ColorRgb(0.1f, 0.2f, 0.3f), state.multiplyColor)
assertEquals(ColorRgb(0.4f, 0.5f, 0.6f), state.screenColor)
}
@Test
fun preparePoseFallsBackToStaticChannelsOutOfRange() {
// The controlling axis sits below the grid's key range → the grid sample hides, and the
// composite falls back to the static channels (mirroring the part draw-order fallback).
val inputs = preparePose(modelWithIsolatedPart(compositeChannels()), mapOf(paramA to -1f))
val state = assertNotNull(inputs.partCompositeStates[PartId("fx")])
assertEquals(0.3f, state.opacity)
}
@Test
fun preparePoseLeavesNonIsolatedPartsOutOfTheMap() {
val plain =
modelWithIsolatedPart(ChannelGrids.Empty)
.let { source -> source.copy(parts = source.parts.map { it.copy(groupMode = PartGroupMode.Grouped) }) }
.withDerivedRenderRoot()
assertTrue(preparePose(plain, emptyMap()).partCompositeStates.isEmpty())
}
private fun drawable(id: String, ownOpacity: Float): Drawable {
val positions = floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f)
val fanned =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0f))),
listOf(KeyformCell(intArrayOf(0), MeshForm(FloatArray(positions.size), opacity = ownOpacity))),
).fanOutMesh()
return Drawable(
id = DrawableId(id),
name = id,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(positions, FloatArray(positions.size), intArrayOf(0, 1, 2)),
// Bundled then fanned, so the fixture matches importer output and the opacity lands on its
// own track rather than being hand-placed.
geometryGrid = fanned.geometry,
channelGrids = fanned.channels,
)
}
/** A part with a static (grid-less) opacity, so the cascade reads it off PartComposite. */
private fun partWith(id: String, mode: PartGroupMode, opacity: Float, children: List<OrgChild>): Part =
Part(id = PartId(id), name = id, children = children, groupMode = mode, composite = PartComposite(opacity = opacity))
private fun cascadeModel(parts: List<Part>, drawables: List<Drawable>, rootChildren: List<OrgChild>): PuppetModel =
PuppetModel(
parameters = listOf(Parameter(paramA, "A", -1f, 1f, 0f)),
parts = parts,
deformers = emptyList(),
drawables = drawables,
rootChildren = rootChildren,
rootPartId = null,
canvasWidth = 0f,
canvasHeight = 0f,
worldOriginX = 0f,
worldOriginZ = 0f,
).withDerivedRenderRoot()
/** The pose-resolved opacity of drawable [id] in [model] at the default pose. */
private fun drawableOpacity(model: PuppetModel, id: String): Float =
preparePose(model, emptyMap()).drawables.first { it.drawableId == DrawableId(id) }.opacity
@Test
fun nonIsolatedPartOpacityDoesNotCascadeToItsDrawables() {
// Cubism only exposes/applies a part's composite opacity while it is Isolated (offscreen drawing);
// a Grouped or PassThrough part's latent composite.opacity is stored but never rendered.
val part = partWith("grp", PartGroupMode.Grouped, opacity = 0.5f, children = listOf(OrgChild.Drawable(DrawableId("d"))))
val model = cascadeModel(listOf(part), listOf(drawable("d", ownOpacity = 0.8f)), listOf(OrgChild.Part(PartId("grp"))))
assertEquals(0.8f, drawableOpacity(model, "d"), 1e-6f, "own opacity only; the non-isolated part's composite opacity is inert")
}
@Test
fun isolatedPartOpacityDoesNotCascadeToDrawables() {
// An isolated part applies its opacity at the composite pass, so its drawable keeps its own opacity
// (the part's 0.5 shows up in partCompositeStates instead - covered above).
val part = partWith("fx", PartGroupMode.Isolated, opacity = 0.5f, children = listOf(OrgChild.Drawable(DrawableId("d"))))
val model = cascadeModel(listOf(part), listOf(drawable("d", ownOpacity = 0.8f)), listOf(OrgChild.Part(PartId("fx"))))
assertEquals(0.8f, drawableOpacity(model, "d"), 1e-6f, "isolated part opacity rides its composite, not the drawable")
}
@Test
fun nestedNonIsolatedPartOpacitiesDoNotCascade() {
val inner = partWith("inner", PartGroupMode.Grouped, opacity = 0.5f, children = listOf(OrgChild.Drawable(DrawableId("d"))))
val outer = partWith("outer", PartGroupMode.PassThrough, opacity = 0.5f, children = listOf(OrgChild.Part(PartId("inner"))))
val model = cascadeModel(listOf(outer, inner), listOf(drawable("d", ownOpacity = 1f)), listOf(OrgChild.Part(PartId("outer"))))
assertEquals(1f, drawableOpacity(model, "d"), 1e-6f, "neither non-isolated part's opacity applies")
}
@Test
fun drawableKeyformColorResolvesInPreparePose() {
// The 5.3 per-art-mesh multiply/screen colors ride their own channel tracks; preparePose must blend
// them onto DrawableDeformInputs so the renderer can tint (a GL-independent proof of the resolve).
val positions = floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f)
val fanned =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0f))),
listOf(
KeyformCell(
intArrayOf(0),
MeshForm(FloatArray(positions.size), multiplyColor = ColorRgb(1f, 0f, 0f), screenColor = ColorRgb(0f, 0f, 0.5f)),
),
),
).fanOutMesh()
val drawable =
Drawable(
id = DrawableId("d"),
name = "d",
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(positions, FloatArray(positions.size), intArrayOf(0, 1, 2)),
geometryGrid = fanned.geometry,
channelGrids = fanned.channels,
)
val model = cascadeModel(emptyList(), listOf(drawable), listOf(OrgChild.Drawable(DrawableId("d"))))
val resolved = preparePose(model, emptyMap()).drawables.first { it.drawableId == DrawableId("d") }
assertEquals(ColorRgb(1f, 0f, 0f), resolved.multiplyColor)
assertEquals(ColorRgb(0f, 0f, 0.5f), resolved.screenColor)
}
@Test
fun nonIsolatedAncestorOpacityDoesNotReachAnIsolatedChild() {
// Neither the non-isolated outer part's opacity nor the isolated inner part's opacity (which rides
// its own composite pass) touches the drawable directly.
val inner = partWith("fx", PartGroupMode.Isolated, opacity = 0.5f, children = listOf(OrgChild.Drawable(DrawableId("d"))))
val outer = partWith("outer", PartGroupMode.Grouped, opacity = 0.5f, children = listOf(OrgChild.Part(PartId("fx"))))
val model = cascadeModel(listOf(outer, inner), listOf(drawable("d", ownOpacity = 1f)), listOf(OrgChild.Part(PartId("outer"))))
assertEquals(1f, drawableOpacity(model, "d"), 1e-6f, "outer's composite opacity is inert; inner's rides its composite")
}
}
@@ -0,0 +1,234 @@
package org.umamo.render.eval
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.PartComposite
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.RenderDrawable
import org.umamo.runtime.model.RenderGroup
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertIs
/**
* Verifies [paintOrder]: drawOrder is the primary key, the parts-tree base order breaks ties. This is
* the unit-test stand-in for the official editor (which we can't re-save under its EULA) - the
* Layer68→600 case is `higherDrawOrderPaintsInFront`.
*/
class RenderOrderTest {
private fun id(name: String) = DrawableId(name)
@Test
fun equalDrawOrderKeepsPartsTreeBaseOrder() {
val base = listOf(id("a"), id("b"), id("c"))
val order = paintOrder(base, base.associateWith { 500f })
assertEquals(base, order)
}
@Test
fun higherDrawOrderPaintsInFront() {
// Layer68 → 600: a backmost drawable raised above the default 500s paints last (frontmost),
// regardless of which part it lives in.
val base = listOf(id("a"), id("b"), id("c"))
val order = paintOrder(base, mapOf(id("a") to 600f, id("b") to 500f, id("c") to 500f))
assertEquals(listOf(id("b"), id("c"), id("a")), order)
}
@Test
fun lowerDrawOrderPaintsBehind() {
val base = listOf(id("a"), id("b"), id("c"))
val order = paintOrder(base, mapOf(id("a") to 500f, id("b") to 500f, id("c") to 400f))
assertEquals(listOf(id("c"), id("a"), id("b")), order)
}
@Test
fun missingDrawOrderTreatedAsCubismDefault() {
val base = listOf(id("a"), id("b"))
// b has no entry → DEFAULT_DRAW_ORDER (500) < a's 600, so b stays behind a.
val order = paintOrder(base, mapOf(id("a") to 600f))
assertEquals(listOf(id("b"), id("a")), order)
}
@Test
fun subIntegerDrawOrderNoiseDoesNotReorder() {
// The keyform blend `Σ wᵢ·500` lands just off 500.0 due to float-summation noise, so a
// raw-float sort reshuffles drawables that should be tied. Quantising `+0.001`→int collapses
// the noise to a true 500 tie, preserving the parts-tree base order. Without quantising,
// `sortedBy` would order c (499.99997) < a (500.0) < b (500.00003) and lift c in front of the rest.
val base = listOf(id("a"), id("b"), id("c"))
val order = paintOrder(base, mapOf(id("a") to 500f, id("b") to 500.00003f, id("c") to 499.99997f))
assertEquals(base, order)
}
@Test
fun fractionalDrawOrderFloorsLikeCubism() {
// Cubism floors `(int)(0.001 + order)`, so 500.6 and 500.9 are still 500 (tie → base order kept),
// and only a full integer step (502) actually moves a drawable.
val base = listOf(id("a"), id("b"), id("c"))
val order = paintOrder(base, mapOf(id("a") to 500.6f, id("b") to 500.9f, id("c") to 502f))
assertEquals(listOf(id("a"), id("b"), id("c")), order)
}
@Test
fun drawOrderGroupConfinesChildrenToTheGroupSlot() {
// An "eye" group (part draw order 600) holds two eye drawables; the root also holds
// back/mid/front drawables. A flat global sort would slot mid (550) BETWEEN eyeLow (510) and
// eyeHigh (590); the group must keep the eyes contiguous at the group's 600 slot, so mid stays
// before the whole group. Within the group the eyes still sort by their own order (510 < 590).
val root =
RenderGroup(
partId = null,
drawOrder = 500,
children =
listOf(
RenderDrawable(id("back")),
RenderDrawable(id("mid")),
RenderGroup(null, 600, listOf(RenderDrawable(id("eyeHigh")), RenderDrawable(id("eyeLow")))),
RenderDrawable(id("front")),
),
)
val drawOrders =
mapOf(
id("back") to 100f,
id("mid") to 550f,
id("eyeLow") to 510f,
id("eyeHigh") to 590f,
id("front") to 900f,
)
val order = renderOrder(root, drawOrders)
assertEquals(listOf(id("back"), id("mid"), id("eyeLow"), id("eyeHigh"), id("front")), order)
// A flat sort would interleave mid between the eyes - the divergence the group fixes.
val flat = paintOrder(order, drawOrders).map { it.raw }
assertEquals(listOf("back", "eyeLow", "mid", "eyeHigh", "front"), flat)
}
@Test
fun flatGroupMatchesGlobalPaintOrder() {
// A group-less model is one flat RenderGroup, so renderOrder reduces exactly to paintOrder.
val ids = listOf(id("a"), id("b"), id("c"))
val root = RenderGroup(null, 500, ids.map { RenderDrawable(it) })
val drawOrders = mapOf(id("a") to 600f, id("b") to 500f, id("c") to 500f)
assertEquals(paintOrder(ids, drawOrders), renderOrder(root, drawOrders))
}
@Test
fun isolatedGroupBecomesAPlanBoundaryAndPlainGroupsFlatten() {
// The fx part is isolated → it must survive as a RenderPlanComposite node (the renderer needs
// the subtree span to composite it as one layer); the plain 700-group stays transparent in the
// plan exactly as it always was in the flat order.
val root =
RenderGroup(
partId = null,
drawOrder = 500,
children =
listOf(
RenderDrawable(id("back")),
RenderGroup(
PartId("fx"),
600,
listOf(RenderDrawable(id("fxHigh")), RenderDrawable(id("fxLow"))),
ChannelGrids.Empty,
PartComposite(),
),
RenderGroup(null, 700, listOf(RenderDrawable(id("plain")))),
RenderDrawable(id("front")),
),
)
val drawOrders =
mapOf(
id("back") to 100f,
id("fxLow") to 510f,
id("fxHigh") to 590f,
id("plain") to 500f,
id("front") to 900f,
)
val plan = renderPlan(root, drawOrders)
assertEquals(4, plan.size, "back, the composite node, plain (flattened), front")
assertEquals(id("back"), assertIs<RenderPlanDrawable>(plan[0]).id)
val compositeNode = assertIs<RenderPlanComposite>(plan[1])
assertEquals(PartId("fx"), compositeNode.partId)
assertEquals(
listOf(id("fxLow"), id("fxHigh")),
compositeNode.children.map { assertIs<RenderPlanDrawable>(it).id },
"the subtree still sorts internally by drawable order",
)
assertEquals(id("plain"), assertIs<RenderPlanDrawable>(plan[2]).id)
assertEquals(id("front"), assertIs<RenderPlanDrawable>(plan[3]).id)
// The flat order is exactly the plan flattened - one sort implementation, two views.
assertEquals(renderOrder(root, drawOrders), flattenRenderPlan(plan))
}
@Test
fun nestedIsolatedGroupsNestInThePlan() {
val inner =
RenderGroup(PartId("inner"), 500, listOf(RenderDrawable(id("leaf"))), ChannelGrids.Empty, PartComposite())
val outer =
RenderGroup(
PartId("outer"),
600,
listOf(RenderDrawable(id("sibling")), inner),
ChannelGrids.Empty,
PartComposite(),
)
val root = RenderGroup(null, 500, listOf(RenderDrawable(id("back")), outer))
val plan = renderPlan(root, mapOf(id("back") to 100f, id("sibling") to 400f, id("leaf") to 500f))
val outerNode = assertIs<RenderPlanComposite>(plan[1])
assertEquals(PartId("outer"), outerNode.partId)
val innerNode = assertIs<RenderPlanComposite>(outerNode.children[1])
assertEquals(PartId("inner"), innerNode.partId)
assertEquals(id("leaf"), assertIs<RenderPlanDrawable>(innerNode.children.single()).id)
}
@Test
fun animatedPartDrawOrderMovesAnIsolatedBoundary() {
// An isolated group is still a draw-order group: its parameter-driven part order moves the
// whole boundary node through the sibling order.
val root =
RenderGroup(
partId = null,
drawOrder = 500,
children =
listOf(
RenderDrawable(id("back")),
RenderGroup(
PartId("fx"),
500,
listOf(RenderDrawable(id("fxA"))),
ChannelGrids.Empty,
PartComposite(),
),
RenderDrawable(id("front")),
),
)
val drawOrders = mapOf(id("back") to 100f, id("fxA") to 500f, id("front") to 900f)
val behind = renderPlan(root, drawOrders, mapOf(PartId("fx") to 300f))
assertIs<RenderPlanComposite>(behind[1], "part order 300 keeps the composite behind front")
val front = renderPlan(root, drawOrders, mapOf(PartId("fx") to 950f))
assertIs<RenderPlanComposite>(front[2], "part order 950 lifts the whole composite frontmost")
}
@Test
fun animatedPartDrawOrderMovesTheWholeGroup() {
// A sub-group's sort key is its (parameter-driven) PART draw order, so the whole arm set swaps
// front/back as the arm parameter moves it 400↔700, without re-sorting its members.
val root =
RenderGroup(
partId = null,
drawOrder = 500,
children =
listOf(
RenderDrawable(id("back")),
RenderGroup(PartId("arm"), 500, listOf(RenderDrawable(id("armA")), RenderDrawable(id("armB")))),
RenderDrawable(id("front")),
),
)
val drawOrders = mapOf(id("back") to 100f, id("armA") to 500f, id("armB") to 500f, id("front") to 900f)
// Part order 300 → the arm group sits behind front (900); 950 → it jumps in front of everything.
val behind = renderOrder(root, drawOrders, mapOf(PartId("arm") to 300f))
assertEquals(listOf(id("back"), id("armA"), id("armB"), id("front")), behind)
val front = renderOrder(root, drawOrders, mapOf(PartId("arm") to 950f))
assertEquals(listOf(id("back"), id("front"), id("armA"), id("armB")), front)
}
}
@@ -0,0 +1,96 @@
package org.umamo.render.eval
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.DEFAULT_DRAW_ORDER
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.PuppetModel
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertNull
/**
* Pins that an UNKEYED drawable renders at its rest mesh instead of vanishing, and that this stays
* distinguishable from the genuinely hidden case.
*
* Keyform authoring makes "unkeyed" a normal state - a drawable that has never been bound to a parameter,
* or one whose last axis was just removed - so a drawable with no grid has to be visible or the rigger
* cannot see the thing they are about to key. Before this, preparePose skipped any drawable with a null
* grid outright and the renderer never even uploaded it.
*
* The two null-ish states are opposites and must not collapse into one: NO GRID means render at rest,
* while a keyed grid whose pose falls outside its key range means hide.
*/
class UnkeyedDrawableRenderTest {
private val paramA = ParameterId("A")
private val drawableId = DrawableId("M")
private fun mesh(): DrawableMesh = DrawableMesh(floatArrayOf(10f, 5f, 20f, 7f), FloatArray(0), intArrayOf(0, 1, 0))
private fun model(drawable: Drawable): PuppetModel =
PuppetModel(
parameters = listOf(Parameter(paramA, "A", -1f, 1f, 0f)),
parts = emptyList(),
deformers = emptyList(),
drawables = listOf(drawable),
rootChildren = listOf(OrgChild.Drawable(drawable.id)),
rootPartId = null,
)
/** With no keyform grid at all the drawable still deforms - to exactly its rest mesh (Y negated). */
@Test
fun anUnkeyedDrawableRendersItsRestMesh() {
val drawable = Drawable(drawableId, "M", null, BlendMode.Normal, emptyList(), mesh(), geometryGrid = null)
val geometry = CpuDeformationEvaluator().evaluate(model(drawable), emptyMap())
val positions =
assertNotNull(geometry.worldPositions[drawableId], "an unkeyed drawable must still produce geometry")
assertEquals(listOf(10f, -5f, 20f, -7f), positions.toList())
}
/** An unkeyed drawable takes the Cubism default scalars rather than being dropped from the pose. */
@Test
fun anUnkeyedDrawableTakesDefaultScalars() {
val drawable = Drawable(drawableId, "M", null, BlendMode.Normal, emptyList(), mesh(), geometryGrid = null)
val geometry = CpuDeformationEvaluator().evaluate(model(drawable), emptyMap())
assertEquals(1f, geometry.opacity[drawableId])
assertEquals(DEFAULT_DRAW_ORDER.toFloat(), geometry.drawOrder[drawableId])
}
/**
* A KEYED drawable whose pose is outside its key range is still hidden. This is the case that must not
* be confused with the one above - out of range is a deliberate authoring device (the toggle-part
* pattern), and turning it into "render at rest" would make hidden art reappear.
*/
@Test
fun anOutOfRangeKeyedDrawableStaysHidden() {
val grid =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0.5f, 1f))),
listOf(
KeyformCell(intArrayOf(0), MeshDeltaForm(FloatArray(4))),
KeyformCell(intArrayOf(1), MeshDeltaForm(FloatArray(4))),
),
)
val drawable = Drawable(drawableId, "M", null, BlendMode.Normal, emptyList(), mesh(), geometryGrid = grid)
// The parameter defaults to 0, below the axis's first key of 0.5.
val geometry = CpuDeformationEvaluator().evaluate(model(drawable), emptyMap())
assertNull(geometry.worldPositions[drawableId], "a pose outside the key range still hides the drawable")
}
/** The gizmo's local-posed read falls back to the rest mesh too, so an unkeyed drawable is editable. */
@Test
fun localPosedFallsBackToTheRestMesh() {
val drawable = Drawable(drawableId, "M", null, BlendMode.Normal, emptyList(), mesh(), geometryGrid = null)
val local = assertNotNull(drawableLocalPosed(model(drawable), emptyMap(), drawableId))
assertEquals(listOf(10f, 5f, 20f, 7f), local.toList(), "local space is the rest mesh, un-negated")
}
}
@@ -0,0 +1,217 @@
package org.umamo.render.pick
import org.umamo.runtime.model.DrawableId
import kotlin.math.sqrt
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Verifies the pure picking math: point-in-triangle, barycentric weights, front-most-by-paint-order
* ranking, the atlas-alpha coverage gate, the front-to-back candidate list, and centrality scoring.
* All pure — alpha is supplied by an injected lambda, so no GL or textures are needed.
*/
class PickerTest {
// A unit square at the origin, two triangles; UVs equal the positions (already in [0,1]).
private val squarePositions = floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f, 0f, 1f)
private val squareUvs = floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f, 0f, 1f)
private val squareIndices = intArrayOf(0, 1, 2, 0, 2, 3)
// An always-opaque sampler for the geometry-only cases.
private val opaque: (DrawableId, Float, Float) -> Float = { _, _, _ -> 1f }
/**
* A point well inside a triangle is contained.
*/
@Test
fun pointInsideTriangle() {
assertTrue(pointInTriangle(0.25f, 0.25f, 0f, 0f, 1f, 0f, 0f, 1f))
}
/**
* A point outside the triangle is not contained.
*/
@Test
fun pointOutsideTriangle() {
assertFalse(pointInTriangle(0.9f, 0.9f, 0f, 0f, 1f, 0f, 0f, 1f))
}
/**
* A point exactly on an edge counts as contained, and winding order does not matter.
*/
@Test
fun pointOnEdgeIsInsideRegardlessOfWinding() {
assertTrue(pointInTriangle(0.5f, 0.5f, 0f, 0f, 1f, 0f, 0f, 1f))
assertTrue(pointInTriangle(0.25f, 0.25f, 0f, 1f, 1f, 0f, 0f, 0f))
}
/**
* A degenerate (collinear) triangle contains points on its span but rejects points off the line.
*/
@Test
fun degenerateTriangle() {
assertTrue(pointInTriangle(0.5f, 0f, 0f, 0f, 1f, 0f, 2f, 0f))
assertFalse(pointInTriangle(0.5f, 0.5f, 0f, 0f, 1f, 0f, 2f, 0f))
}
/**
* Barycentric weights sum to 1, give a unit weight at a vertex, and fall back to thirds when
* degenerate.
*/
@Test
fun barycentricWeightsBasics() {
val centroid = barycentricWeights(1f / 3f, 1f / 3f, 0f, 0f, 1f, 0f, 0f, 1f)
assertEquals(1f, centroid[0] + centroid[1] + centroid[2], 1e-4f)
val atFirst = barycentricWeights(0f, 0f, 0f, 0f, 1f, 0f, 0f, 1f)
assertEquals(1f, atFirst[0], 1e-4f)
assertEquals(0f, atFirst[1], 1e-4f)
assertEquals(0f, atFirst[2], 1e-4f)
val degenerate = barycentricWeights(0.5f, 0.5f, 0f, 0f, 0f, 0f, 0f, 0f)
assertEquals(1f / 3f, degenerate[0], 1e-4f)
}
/**
* A point inside a single opaque drawable's mesh picks that drawable.
*/
@Test
fun picksContainingDrawable() {
val id = DrawableId("square")
val hit =
pickDrawable(
0.5f,
0.5f,
mapOf(id to squarePositions),
mapOf(id to squareIndices),
mapOf(id to squareUvs),
mapOf(id to 0f),
opaque,
)
assertEquals(id, hit)
}
/**
* A point outside every mesh picks nothing.
*/
@Test
fun pointOutsideAllReturnsNull() {
val id = DrawableId("square")
val hit =
pickDrawable(
5f,
5f,
mapOf(id to squarePositions),
mapOf(id to squareIndices),
mapOf(id to squareUvs),
mapOf(id to 0f),
opaque,
)
assertNull(hit)
}
/**
* Among overlapping opaque drawables, the highest front-rank (the renderer's resolved paint order,
* front = higher) wins — not the raw draw-order scalar, which ignores the group hierarchy.
*/
@Test
fun overlappingPicksHighestFrontRank() {
val under = DrawableId("under")
val over = DrawableId("over")
val hit =
pickDrawable(
0.5f,
0.5f,
mapOf(under to squarePositions, over to squarePositions),
mapOf(under to squareIndices, over to squareIndices),
mapOf(under to squareUvs, over to squareUvs),
mapOf(under to 3f, over to 7f), // over is drawn later (more front)
opaque,
)
assertEquals(over, hit)
}
/**
* A click on a transparent texel is rejected: the front mesh is transparent there, so the opaque mesh
* behind it is picked. Inverting the alpha picks the front one.
*/
@Test
fun transparentOverhangRejectedSoBehindWins() {
val front = DrawableId("front")
val back = DrawableId("back")
val positions = mapOf(front to squarePositions, back to squarePositions)
val indices = mapOf(front to squareIndices, back to squareIndices)
val uvs = mapOf(front to squareUvs, back to squareUvs)
val rank = mapOf(front to 9f, back to 1f) // front is more front, but transparent here
val frontTransparent: (DrawableId, Float, Float) -> Float = { id, _, _ -> if (id == front) 0f else 1f }
assertEquals(back, pickDrawable(0.5f, 0.5f, positions, indices, uvs, rank, frontTransparent))
val frontOpaque: (DrawableId, Float, Float) -> Float = { id, _, _ -> if (id == front) 1f else 1f }
assertEquals(front, pickDrawable(0.5f, 0.5f, positions, indices, uvs, rank, frontOpaque))
}
/**
* A drawable not in the front-rank map (not drawn this frame) is skipped.
*/
@Test
fun drawableAbsentFromFrontRankSkipped() {
val id = DrawableId("ghost")
val hit =
pickDrawable(
0.5f,
0.5f,
mapOf(id to squarePositions),
mapOf(id to squareIndices),
mapOf(id to squareUvs),
emptyMap(), // not drawn → no rank
opaque,
)
assertNull(hit)
}
/**
* pickAllDrawables returns every opaque candidate front-to-back; a fully transparent one is absent.
*/
@Test
fun pickAllIsFrontToBackAndAlphaGated() {
val back = DrawableId("back")
val mid = DrawableId("mid")
val front = DrawableId("front")
val positions = mapOf(back to squarePositions, mid to squarePositions, front to squarePositions)
val indices = mapOf(back to squareIndices, mid to squareIndices, front to squareIndices)
val uvs = mapOf(back to squareUvs, mid to squareUvs, front to squareUvs)
val rank = mapOf(back to 0f, mid to 1f, front to 2f)
// mid is transparent at the click, so it drops out.
val sampler: (DrawableId, Float, Float) -> Float = { id, _, _ -> if (id == mid) 0f else 1f }
val candidates =
pickAllDrawables(0.5f, 0.5f, positions, indices, uvs, rank, atlasSizeOf = { null }, sampleAlpha = sampler)
assertEquals(listOf(front, back), candidates.map { it.id }) // front-to-back, mid gated out
assertTrue(candidates.all { it.centrality == 1f }) // untextured (null atlas size) ⇒ full centrality
}
/**
* Centrality is higher for a hit deep in the opaque region than for one near a transparent boundary.
*/
@Test
fun centralityDeepBeatsBoundary() {
val id = DrawableId("art")
val centerU = 0.5f
val centerV = 0.5f
val radiusUv = 40f / 256f // opaque disc of ~40 texels radius on a 256² atlas
val discField: (DrawableId, Float, Float) -> Float = { _, u, v ->
val du = u - centerU
val dv = v - centerV
if (sqrt(du * du + dv * dv) <= radiusUv) 1f else 0f
}
val deep = centralityAt(id, centerU, centerV, 256, 256, discField)
val nearEdge = centralityAt(id, centerU + 35f / 256f, centerV, 256, 256, discField)
assertTrue(deep > nearEdge, "a central hit ($deep) should score above a near-boundary hit ($nearEdge)")
}
}
@@ -0,0 +1,69 @@
package org.umamo.render.pick
import org.umamo.runtime.model.DrawableId
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* Verifies the pure Object-mode region enclosure: centroids reduce a drawable to a single test point, and box
* / circle enclosure select exactly the drawables whose centroid falls inside - including the decisive case
* that a large layer whose centroid sits outside a grazing region is NOT grabbed (centroid-inside, not
* any-vertex-touching).
*/
class RegionPickTest {
// A small square drawable centerd at (1, 1).
private fun square(): FloatArray = floatArrayOf(0f, 0f, 2f, 0f, 0f, 2f, 2f, 2f)
// A full-canvas layer spanning (-100, -100)..(100, 100); its centroid is the origin.
private fun canvasLayer(): FloatArray = floatArrayOf(-100f, -100f, 100f, -100f, -100f, 100f, 100f, 100f)
/** A drawable's centroid is the mean of its interleaved vertices; an empty array is skipped. */
@Test
fun centroidIsVertexMean() {
val centroids = drawableCentroids(mapOf(DrawableId("s") to square(), DrawableId("blank") to FloatArray(0)))
assertEquals(1f, centroids.getValue(DrawableId("s"))[0], "centroid x")
assertEquals(1f, centroids.getValue(DrawableId("s"))[1], "centroid y")
assertTrue(DrawableId("blank") !in centroids, "an empty array has no centroid")
}
/** Box select selects a drawable whose centroid is inside and excludes one whose centroid is outside. */
@Test
fun boxSelectsByCentroid() {
val centroids = drawableCentroids(mapOf(DrawableId("in") to square(), DrawableId("out") to canvasLayer()))
// A box around (1,1) that does NOT contain the origin.
val enclosed = drawablesInBox(centroids, minX = 0.5f, minY = 0.5f, maxX = 1.5f, maxY = 1.5f)
assertEquals(setOf(DrawableId("in")), enclosed, "only the drawable centerd in the box is selected")
}
/** A box grazing a full-canvas layer's edge does not grab it - its centroid (the origin) is far outside. */
@Test
fun grazingBoxDoesNotGrabFullCanvasLayer() {
val centroids = drawableCentroids(mapOf(DrawableId("canvas") to canvasLayer()))
// A box in the top-right corner that overlaps the layer's geometry but not its centroid at the origin.
val enclosed = drawablesInBox(centroids, minX = 50f, minY = 50f, maxX = 90f, maxY = 90f)
assertTrue(enclosed.isEmpty(), "centroid-inside means a grazing box does not select the whole layer")
}
/** Circle select selects by centroid-within-radius; a centroid outside the disc is excluded. */
@Test
fun circleSelectsByCentroidWithinRadius() {
// "near" centroid (1,1) sits at distance sqrt(2) ~= 1.41 from (1,1)'s... the canvas centroid is the origin.
val centroids = drawableCentroids(mapOf(DrawableId("near") to square(), DrawableId("far") to canvasLayer()))
// Center at (1,1), radius 0.5: the square's centroid (1,1) is inside, the origin (distance ~1.41) is not.
assertEquals(setOf(DrawableId("near")), drawablesInCircle(centroids, centerX = 1f, centerY = 1f, radius = 0.5f))
// A radius of 1.5 (> the ~1.41 distance to the origin) also encloses the canvas layer's centroid.
val reaching = drawablesInCircle(centroids, centerX = 1f, centerY = 1f, radius = 1.5f)
assertTrue(DrawableId("far") in reaching, "a centroid within the radius is enclosed")
assertTrue(DrawableId("near") in reaching, "the closer centroid is enclosed too")
}
/** Empty geometry encloses nothing. */
@Test
fun emptyGeometryEnclosesNothing() {
assertTrue(drawablesInBox(emptyMap(), 0f, 0f, 1f, 1f).isEmpty())
assertTrue(drawablesInCircle(emptyMap(), 0f, 0f, 1f).isEmpty())
}
}
@@ -0,0 +1,137 @@
package org.umamo.render.pick
import org.umamo.render.ViewportCamera
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Verifies the pure screen-space geometry the gizmo overlays (and the future UV editor) pick with:
* the world-to-screen projection and its inverse, nearest-within-radius vertex and edge hit tests,
* the centroid tie-break for overlapping faces, and the box / circle enclosure rules (vertex inside,
* edge both-endpoints / segment-overlap, face by centroid).
*/
class ScreenSpacePickTest {
private val viewportWidth = 400
private val viewportHeight = 300
// A centered 1:1 camera: world (0, 0) projects to screen (200, 150) and one world unit is one pixel.
private val camera = ViewportCamera(0f, 0f, 1f)
// A unit-quad-scaled mesh: v0 bottom-left origin, v1 right, v2 up, v3 diagonal (world y is up).
// Screens at the fixed camera: v0 (200, 150), v1 (210, 150), v2 (200, 140), v3 (210, 140).
private val positions = floatArrayOf(0f, 0f, 10f, 0f, 0f, 10f, 10f, 10f)
private val triangleIndices = intArrayOf(0, 1, 2, 1, 3, 2)
// The quad's five unique edges, in a fixed ordinal order the assertions reference.
private val edgeEndpoints = intArrayOf(0, 1, 1, 2, 0, 2, 1, 3, 2, 3)
/** The projection round-trips exactly and flips Y (world up = screen up = smaller y). */
@Test
fun projectionRoundTripsAndFlipsY() {
val zoomedCamera = ViewportCamera(centerX = 5f, centerY = -3f, zoom = 2f)
val worldX = 12.5f
val worldZ = -7.25f
val screenX = worldToScreenX(worldX, zoomedCamera, viewportWidth)
val screenY = worldToScreenY(worldZ, zoomedCamera, viewportHeight)
assertEquals(worldX, screenToWorldX(screenX, zoomedCamera, viewportWidth), 1e-4f, "x round-trips")
assertEquals(worldZ, screenToWorldZ(screenY, zoomedCamera, viewportHeight), 1e-4f, "y round-trips")
val higherY = worldToScreenY(worldZ + 1f, zoomedCamera, viewportHeight)
assertTrue(higherY < screenY, "a higher world point draws at a smaller screen y")
}
/** hitTestVertex picks the nearest vertex within the radius and misses outside it. */
@Test
fun hitTestVertexPicksNearestWithinRadius() {
// Screen (208, 150): 8 px from v1's projection, 8+ px from v0's - v1 is nearer.
assertEquals(1, hitTestVertex(positions, 208f, 150f, 10f, camera, viewportWidth, viewportHeight))
// Nothing within a 3 px radius at that point.
assertNull(hitTestVertex(positions, 205f, 150f, 2f, camera, viewportWidth, viewportHeight))
}
/** parameterAlongSegment returns the unclamped line parameter (and 0.5 for a degenerate segment). */
@Test
fun parameterAlongSegmentProjectsOntoTheLine() {
assertEquals(0.5f, parameterAlongSegment(5f, 4f, 0f, 0f, 10f, 0f), 1e-4f)
assertEquals(1.3f, parameterAlongSegment(13f, 0f, 0f, 0f, 10f, 0f), 1e-4f)
assertEquals(0.5f, parameterAlongSegment(3f, 4f, 0f, 0f, 0f, 0f), 1e-4f)
}
/** distanceToSegment projects onto the segment, clamps at the endpoints, and survives degeneracy. */
@Test
fun distanceToSegmentClampsToEndpoints() {
// Perpendicular drop onto the middle of a horizontal segment.
assertEquals(4f, distanceToSegment(5f, 4f, 0f, 0f, 10f, 0f), 1e-4f)
// Beyond the end: the distance is to the endpoint, not the infinite line.
assertEquals(5f, distanceToSegment(13f, 4f, 0f, 0f, 10f, 0f), 1e-4f)
// A zero-length segment measures as the distance to its single point.
assertEquals(5f, distanceToSegment(3f, 4f, 0f, 0f, 0f, 0f), 1e-4f)
}
/** hitTestEdge returns the ordinal of the nearest segment within the radius. */
@Test
fun hitTestEdgePicksNearestSegment() {
// Screen (205, 152): 2 px below the v0-v1 segment (ordinal 0), farther from every other edge.
assertEquals(0, hitTestEdge(positions, edgeEndpoints, 205f, 152f, 10f, camera, viewportWidth, viewportHeight))
// Screen (210, 145): on the vertical v1-v3 segment (ordinal 3).
assertEquals(3, hitTestEdge(positions, edgeEndpoints, 210f, 145f, 10f, camera, viewportWidth, viewportHeight))
// Far from everything within a tight radius.
assertNull(hitTestEdge(positions, edgeEndpoints, 250f, 200f, 5f, camera, viewportWidth, viewportHeight))
// An edge referencing a missing vertex is skipped rather than crashing.
assertNull(hitTestEdge(positions, intArrayOf(0, 9), 205f, 150f, 10f, camera, viewportWidth, viewportHeight))
}
/** hitTestFace picks a containing triangle, breaking overlaps by the nearest centroid. */
@Test
fun hitTestFaceUsesCentroidTieBreak() {
// Screen (202, 148) = world (2, 2): inside triangle 0 only.
assertEquals(0, hitTestFace(positions, triangleIndices, 202f, 148f, camera, viewportWidth, viewportHeight))
// Screen (208, 142) = world (8, 8): inside triangle 1 only.
assertEquals(1, hitTestFace(positions, triangleIndices, 208f, 142f, camera, viewportWidth, viewportHeight))
// Outside the quad entirely.
assertNull(hitTestFace(positions, triangleIndices, 250f, 250f, camera, viewportWidth, viewportHeight))
// Two coincident triangles both contain the pointer: the one with the nearer centroid wins.
// Triangle 0 spans the quad's lower-left half; triangle 1 (here duplicated smaller) hugs v0.
val overlappingPositions = floatArrayOf(0f, 0f, 10f, 0f, 0f, 10f, 4f, 0f, 0f, 4f)
val overlappingTriangles = intArrayOf(0, 1, 2, 0, 3, 4)
// World (1, 1) is inside both; the small triangle's centroid is much closer.
assertEquals(1, hitTestFace(overlappingPositions, overlappingTriangles, 201f, 149f, camera, viewportWidth, viewportHeight))
}
/** verticesInBox encloses by screen position, corner order agnostic. */
@Test
fun verticesInBoxEnclosesByScreenPosition() {
// A box around v0 and v2's column (screen x 195..205, y 135..155).
assertEquals(setOf(0, 2), verticesInBox(positions, 205f, 135f, 195f, 155f, camera, viewportWidth, viewportHeight))
// The whole quad.
assertEquals(setOf(0, 1, 2, 3), verticesInBox(positions, 195f, 135f, 215f, 155f, camera, viewportWidth, viewportHeight))
// An empty region.
assertEquals(emptySet(), verticesInBox(positions, 0f, 0f, 50f, 50f, camera, viewportWidth, viewportHeight))
}
/** edgesInBox requires both endpoints inside (Blender's rule); facesInBox uses the centroid. */
@Test
fun boxRulesForEdgesAndFaces() {
// The v0-v2 column box encloses edge ordinal 2 (0-2) only - every other edge has an endpoint outside.
assertEquals(setOf(2), edgesInBox(positions, edgeEndpoints, 205f, 135f, 195f, 155f, camera, viewportWidth, viewportHeight))
// Triangle 0's centroid is world (10/3, 10/3) = screen (~203.3, ~146.7); a tight box around it
// selects face 0 only even though its corners poke out.
assertEquals(setOf(0), facesInBox(positions, triangleIndices, 202f, 145f, 205f, 148f, camera, viewportWidth, viewportHeight))
}
/** The circle brush encloses vertices by distance, edges by segment overlap, faces by centroid. */
@Test
fun circleRulesPerDomain() {
// A 6 px brush at v1's projection: only v1 within reach.
assertEquals(setOf(1), verticesInCircle(positions, 210f, 150f, 6f, camera, viewportWidth, viewportHeight))
// The same brush touches every edge incident to v1 (ordinals 0: 0-1, 1: 1-2, 3: 1-3).
assertEquals(setOf(0, 1, 3), edgesInCircle(positions, edgeEndpoints, 210f, 150f, 6f, camera, viewportWidth, viewportHeight))
// A 3 px brush at triangle 0's centroid paints face 0 only.
assertEquals(setOf(0), facesInCircle(positions, triangleIndices, 203.3f, 146.7f, 3f, camera, viewportWidth, viewportHeight))
// A brush over empty canvas paints nothing.
assertEquals(emptySet(), verticesInCircle(positions, 50f, 50f, 10f, camera, viewportWidth, viewportHeight))
}
}
@@ -0,0 +1,45 @@
package org.umamo.render.puppet
import org.umamo.runtime.model.AlphaBlendMode
import org.umamo.runtime.model.BlendMode
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* An offscreen composite runs over the FULL viewport, so where its layer has no coverage the layer's
* source alpha is 0 and the composite must leave the destination untouched. This was NOT true while
* Out was misread as Porter-Duff SRC-out (destination factor 0): an empty Out layer wrote transparent
* over every pixel and blanked the whole frame - which is what a deformer-hidden Out mesh (modelA's
* hologram overlay at ParamHologram=0) did to the entire character. The corrected DST-flavored Out
* (Fa = 0, Fb = 1-as) preserves an untouched destination inherently, as do the other four modes.
*
* This pins the invariant at the reference level for every alpha mode; `CompositeSweepTest` then pins
* the composite shader to this reference, so the two cannot drift.
*/
class BlendMathEmptyLayerTest {
private val destinations =
listOf(
floatArrayOf(0.4f, 0.2f, 0.7f, 1.0f), // opaque backdrop (the grid / an opaque character pixel)
floatArrayOf(0.1f, 0.1f, 0.1f, 0.5f), // semi-transparent
floatArrayOf(0.0f, 0.0f, 0.0f, 0.0f), // fully transparent
)
@Test
fun anEmptyLayerPreservesTheDestinationForEveryAlphaMode() {
val emptySource = floatArrayOf(0f, 0f, 0f, 0f)
for (alphaMode in AlphaBlendMode.entries) {
for (colorMode in listOf(BlendMode.Normal, BlendMode.Multiply, BlendMode.Overlay, BlendMode.Color)) {
for (destination in destinations) {
val result = compositeReference(emptySource, destination, colorMode, alphaMode)
for (channel in 0 until 4) {
assertTrue(
kotlin.math.abs(result[channel] - destination[channel]) < 1e-6f,
"empty layer under $colorMode / $alphaMode must preserve the destination " +
"(channel $channel: got ${result[channel]}, expected ${destination[channel]})",
)
}
}
}
}
}
}
@@ -0,0 +1,106 @@
package org.umamo.render.puppet
import org.umamo.render.ContentBounds
import org.umamo.render.eval.DeformedGeometry
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.PuppetModel
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Pins [contentBoundsOf] and the fallback beside it: the extent spans only the shown drawables, each span
* is floored at 1, nothing shown measures as null, and an empty view frames the canvas. Reachable without
* a GPU, unlike the framing path in the renderer.
*/
class ContentBoundsEvalTest {
private fun geometryOf(vararg drawables: Pair<String, FloatArray>): DeformedGeometry =
DeformedGeometry(
worldPositions = drawables.associate { (id, positions) -> DrawableId(id) to positions },
drawOrder = emptyMap(),
opacity = emptyMap(),
)
@Test
fun contentBoundsOfSpansEveryShownVertex() {
val geometry = geometryOf("a" to floatArrayOf(-10f, -20f, 30f, 5f), "b" to floatArrayOf(0f, 40f))
val bounds = assertNotNull(contentBoundsOf(geometry, setOf(DrawableId("a"), DrawableId("b"))))
assertEquals(-10f, bounds.minX, "left edge is the smallest x across both meshes")
assertEquals(-20f, bounds.minY, "bottom edge is the smallest y across both meshes")
assertEquals(40f, bounds.width, "width spans -10..30")
assertEquals(60f, bounds.height, "height spans -20..40")
}
@Test
fun contentBoundsOfIgnoresHiddenDrawables() {
// The hidden mesh is far larger; if the filter regressed, the bounds would swell to it.
val geometry = geometryOf("shown" to floatArrayOf(0f, 0f, 10f, 10f), "hidden" to floatArrayOf(-500f, -500f, 500f, 500f))
val bounds = assertNotNull(contentBoundsOf(geometry, setOf(DrawableId("shown"))))
assertEquals(0f, bounds.minX)
assertEquals(0f, bounds.minY)
assertEquals(10f, bounds.width, "the hidden full-canvas mesh must not stretch the framing")
assertEquals(10f, bounds.height)
}
@Test
fun contentBoundsOfFloorsDegenerateSpansAtOne() {
// A single vertex has zero extent; the floor is what keeps a fit from dividing by zero.
val bounds = assertNotNull(contentBoundsOf(geometryOf("dot" to floatArrayOf(7f, 9f)), setOf(DrawableId("dot"))))
assertEquals(1f, bounds.width, "a zero-width extent floors at 1")
assertEquals(1f, bounds.height, "a zero-height extent floors at 1")
}
/**
* Nothing shown is nothing to measure: null, never a rectangle left at the float extremes - a camera
* fitted to that sits where the grid has no precision to draw with, and the viewport goes blank.
*/
@Test
fun contentBoundsOfIsNullWhenNothingIsShown() {
assertNull(contentBoundsOf(geometryOf("a" to floatArrayOf(0f, 0f)), emptySet()), "every drawable hidden")
assertNull(contentBoundsOf(geometryOf(), emptySet()), "an empty model")
assertNull(contentBoundsOf(geometryOf("empty" to FloatArray(0)), setOf(DrawableId("empty"))), "a shown drawable with no vertices")
}
/** An empty view frames the canvas, which world space holds at x in [0, width] and y in [-height, 0]. */
@Test
fun anEmptyViewFramesTheCanvas() {
val bounds = emptyContentBoundsOf(emptyModel(canvasWidth = 1200f, canvasHeight = 800f))
assertEquals(ContentBounds(0f, -800f, 1200f, 800f), bounds)
}
/** With no canvas either, it frames a square around the world origin, so the origin's axes are on screen. */
@Test
fun anEmptyViewWithNoCanvasFramesTheWorldOrigin() {
val bounds = emptyContentBoundsOf(emptyModel(canvasWidth = 0f, canvasHeight = 0f, worldOriginX = 40f, worldOriginZ = -60f))
assertEquals(40f, bounds.minX + bounds.width / 2f, "centered on the origin's x")
assertEquals(-60f, bounds.minY + bounds.height / 2f, "centered on the origin's y")
assertTrue(bounds.width > 1f && bounds.height > 1f, "with room to work in, not a degenerate point")
}
/**
* A model with nothing in it.
*
* @param Float canvasWidth The canvas width, or 0 for none.
* @param Float canvasHeight The canvas height, or 0 for none.
* @param Float worldOriginX The world origin's x.
* @param Float worldOriginZ The world origin's z (up).
* @return PuppetModel The model.
*/
private fun emptyModel(canvasWidth: Float, canvasHeight: Float, worldOriginX: Float = 0f, worldOriginZ: Float = 0f): PuppetModel =
PuppetModel(
parameters = emptyList(),
parts = emptyList(),
deformers = emptyList(),
drawables = emptyList(),
rootChildren = emptyList(),
rootPartId = null,
canvasWidth = canvasWidth,
canvasHeight = canvasHeight,
worldOriginX = worldOriginX,
worldOriginZ = worldOriginZ,
)
}
@@ -0,0 +1,104 @@
package org.umamo.render.puppet
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.ParameterId
import kotlin.test.Test
import kotlin.test.assertEquals
/**
* Pins [keyformCellCount] and [buildDeltaTexels] - the morph's Δ table layout. This is the data the
* vertex shader texel-fetches per active corner, so a layout slip mis-deforms every mesh; until now it
* was reachable only through the corpus-gated GPU test, which does not run in CI.
*/
class DeltaTexelsTest {
private val paramA = ParameterId("A")
private val paramB = ParameterId("B")
/** Reads texel (vertex, cell) out of the row-major RG buffer. */
private fun texelAt(texels: FloatArray, cellCount: Int, vertexIndex: Int, cellIndex: Int): Pair<Float, Float> {
val at = (vertexIndex * cellCount + cellIndex) * 2
return texels[at] to texels[at + 1]
}
@Test
fun keyformCellCountIsTheProductOfAxisKeyCounts() {
val grid =
KeyformGrid<MeshDeltaForm>(
axes = listOf(KeyformAxis(paramA, floatArrayOf(-1f, 0f, 1f)), KeyformAxis(paramB, floatArrayOf(0f, 1f))),
cells = emptyList(),
)
assertEquals(6, keyformCellCount(grid), "3 keys x 2 keys = 6 cells")
}
@Test
fun keyformCellCountFloorsAtOneForAnAxislessGrid() {
val grid = KeyformGrid<MeshDeltaForm>(axes = emptyList(), cells = emptyList())
assertEquals(1, keyformCellCount(grid), "an axis-less grid still has its single rest cell")
}
@Test
fun buildDeltaTexelsPlacesEachCellInItsLinearColumn() {
// Two vertices, two cells along one axis. Cell 0 shifts vertex 1 only; cell 1 shifts vertex 0 only,
// so a row/column transpose or an off-by-one column would be caught.
val grid =
KeyformGrid(
axes = listOf(KeyformAxis(paramA, floatArrayOf(0f, 1f))),
cells =
listOf(
KeyformCell(intArrayOf(0), MeshDeltaForm(floatArrayOf(0f, 0f, 5f, 6f))),
KeyformCell(intArrayOf(1), MeshDeltaForm(floatArrayOf(7f, 8f, 0f, 0f))),
),
)
val texels = buildDeltaTexels(grid, vertexCount = 2, cellCount = 2)
assertEquals(2 * 2 * 2, texels.size, "vertexCount * cellCount * 2")
assertEquals(0f to 0f, texelAt(texels, 2, vertexIndex = 0, cellIndex = 0))
assertEquals(7f to 8f, texelAt(texels, 2, vertexIndex = 0, cellIndex = 1))
assertEquals(5f to 6f, texelAt(texels, 2, vertexIndex = 1, cellIndex = 0))
assertEquals(0f to 0f, texelAt(texels, 2, vertexIndex = 1, cellIndex = 1))
}
@Test
fun buildDeltaTexelsUsesTheAxisMajorLinearIndex() {
// Strides run axis 0 fastest (stride 1), so coordinate (0,1) on a 2x2 grid is linear index 2 -
// the same indexing WeightedCell.linearIndex carries into the shader. A stride flip lands it at 1.
val grid =
KeyformGrid(
axes = listOf(KeyformAxis(paramA, floatArrayOf(0f, 1f)), KeyformAxis(paramB, floatArrayOf(0f, 1f))),
cells = listOf(KeyformCell(intArrayOf(0, 1), MeshDeltaForm(floatArrayOf(9f, 9f)))),
)
val texels = buildDeltaTexels(grid, vertexCount = 1, cellCount = 4)
assertEquals(9f to 9f, texelAt(texels, 4, vertexIndex = 0, cellIndex = 2), "coordinate (0,1) lands in column 2")
assertEquals(0f to 0f, texelAt(texels, 4, vertexIndex = 0, cellIndex = 1), "column 1 is coordinate (1,0), unkeyed here")
}
@Test
fun buildDeltaTexelsZeroFillsAMissingCell() {
// A grid whose cells do not cover every combination: the absent cell means no offset from rest.
val grid =
KeyformGrid(
axes = listOf(KeyformAxis(paramA, floatArrayOf(0f, 1f))),
cells = listOf(KeyformCell(intArrayOf(0), MeshDeltaForm(floatArrayOf(3f, 4f)))),
)
val texels = buildDeltaTexels(grid, vertexCount = 1, cellCount = 2)
assertEquals(3f to 4f, texelAt(texels, 2, 0, 0))
assertEquals(0f to 0f, texelAt(texels, 2, 0, 1), "the unkeyed cell contributes no delta")
}
@Test
fun buildDeltaTexelsZeroFillsWhenTheDeltaArrayIsShorterThanTheMesh() {
// Reachable in real models: the form carries fewer vertices than the mesh. The short tail reads as
// rest rather than running off the end.
val grid =
KeyformGrid(
axes = listOf(KeyformAxis(paramA, floatArrayOf(0f))),
cells = listOf(KeyformCell(intArrayOf(0), MeshDeltaForm(floatArrayOf(1f, 2f)))),
)
val texels = buildDeltaTexels(grid, vertexCount = 3, cellCount = 1)
assertEquals(1f to 2f, texelAt(texels, 1, vertexIndex = 0, cellIndex = 0))
assertEquals(0f to 0f, texelAt(texels, 1, vertexIndex = 1, cellIndex = 0), "vertex past the delta array reads rest")
assertEquals(0f to 0f, texelAt(texels, 1, vertexIndex = 2, cellIndex = 0))
}
}
@@ -0,0 +1,35 @@
package org.umamo.render.puppet
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/** Pins [fallbackColorFor]: stable per id, distinct across ids, and always in the readable mid-band. */
class FallbackColorTest {
@Test
fun fallbackColorForIsStableForTheSameId() {
// The point of hashing the id rather than cycling a palette: a drawable keeps its color across
// reorders and reloads.
assertTrue(fallbackColorFor("mesh_a").contentEquals(fallbackColorFor("mesh_a")))
}
@Test
fun fallbackColorForDiffersAcrossIds() {
assertTrue(!fallbackColorFor("mesh_a").contentEquals(fallbackColorFor("mesh_b")), "neighbouring meshes must be tellable apart")
}
@Test
fun fallbackColorForStaysInTheReadableMidBand() {
// 0.35 floor + 0.6 span keeps every channel mid-bright, so the mesh reads against both the light
// and dark grid backdrops.
for (id in listOf("", "a", "some_long_drawable_id", "ParamAngleX", "0")) {
val color = fallbackColorFor(id)
assertEquals(4, color.size, "RGBA")
for (channelIndex in 0..2) {
assertTrue(color[channelIndex] >= 0.35f, "$id channel $channelIndex is at or above the floor")
assertTrue(color[channelIndex] <= 0.95f, "$id channel $channelIndex is at or below floor + span")
}
assertEquals(0.85f, color[3], "alpha is fixed")
}
}
}
@@ -0,0 +1,179 @@
package org.umamo.render.puppet
import org.umamo.render.glsl.MAX_GLUES
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.Glue
import org.umamo.runtime.model.GluePair
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.PuppetModel
import kotlin.test.Test
import kotlin.test.assertContentEquals
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* Pins [planGlueLayout] - the glue addressing the GPU weld reads.
*
* This logic had NO coverage of any kind before it was extracted: `GpuDeformValidationTest` excludes glue
* by design, and `GlueTest` / `GlueCorpusTest` only exercise the CPU weld, which does not use these
* offsets or attributes at all. `GpuGlueValidationTest` now covers the same ground end-to-end through a
* GPU, but needs a display; these run anywhere.
*/
class GlueLayoutTest {
private val paramA = ParameterId("A")
/** A drawable with [vertexCount] vertices; geometry values are irrelevant to addressing. */
private fun drawable(id: String, vertexCount: Int): Drawable {
val positions = FloatArray(vertexCount * 2)
return Drawable(
id = DrawableId(id),
name = id,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(positions, FloatArray(positions.size), IntArray(0)),
geometryGrid =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0f))),
listOf(KeyformCell(intArrayOf(0), MeshDeltaForm(FloatArray(positions.size)))),
),
)
}
private fun model(drawables: List<Drawable>, glues: List<Glue>): PuppetModel =
PuppetModel(
parameters = listOf(Parameter(paramA, "A", -1f, 1f, 0f)),
parts = emptyList(),
deformers = emptyList(),
drawables = drawables,
rootChildren = drawables.map { OrgChild.Drawable(it.id) },
rootPartId = null,
glues = glues,
canvasWidth = 0f,
canvasHeight = 0f,
worldOriginX = 0f,
worldOriginZ = 0f,
)
@Test
fun planGlueLayoutIsEmptyWithoutGlue() {
val layout = planGlueLayout(model(listOf(drawable("a", 3)), emptyList()))
assertTrue(layout.glueMeshIds.isEmpty())
assertEquals(0, layout.globalVertexCount, "no glue means no shared store")
assertTrue(layout.attributesById.isEmpty())
}
@Test
fun planGlueLayoutAssignsOffsetsInDrawableOrderSkippingUngluedMeshes() {
// "middle" is not glued, so it takes no region: offsets follow model.drawables order over the
// GLUED meshes only. Both the pass-1 write and the pass-2 partner read depend on this exactly.
val drawables = listOf(drawable("a", 4), drawable("middle", 9), drawable("b", 2))
val glue = Glue(DrawableId("a"), DrawableId("b"), listOf(GluePair(0, 0, 0.5f, 0.5f)))
val layout = planGlueLayout(model(drawables, listOf(glue)))
assertEquals(setOf(DrawableId("a"), DrawableId("b")), layout.glueMeshIds)
assertEquals(0, layout.baseOffsetById[DrawableId("a")], "the first glued mesh starts the store")
assertEquals(4, layout.baseOffsetById[DrawableId("b")], "the next glued mesh follows a's 4 vertices")
assertEquals(null, layout.baseOffsetById[DrawableId("middle")], "an unglued mesh gets no region")
assertEquals(6, layout.globalVertexCount, "4 + 2; the unglued mesh's 9 vertices are not in the store")
}
@Test
fun planGlueLayoutDefaultsEveryVertexToAnUngluedSelfWeld() {
val drawables = listOf(drawable("a", 3), drawable("b", 3))
val glue = Glue(DrawableId("a"), DrawableId("b"), emptyList())
val layout = planGlueLayout(model(drawables, listOf(glue)))
val attributesB = layout.attributesById.getValue(DrawableId("b"))
// Self-pointing by GLOBAL index (b starts at 3), so the weld is arithmetically a no-op.
assertContentEquals(intArrayOf(3, 4, 5), attributesB.partnerIndex, "an unglued vertex points at itself")
assertContentEquals(intArrayOf(-1, -1, -1), attributesB.glueIndex, "-1 means no glue")
assertContentEquals(floatArrayOf(0f, 0f, 0f), attributesB.weldWeight, "zero weight is a no-op weld")
}
@Test
fun planGlueLayoutPointsEachPairAtItsPartnerByGlobalIndex() {
val drawables = listOf(drawable("a", 4), drawable("b", 4))
val glue = Glue(DrawableId("a"), DrawableId("b"), listOf(GluePair(1, 2, 0.25f, 0.75f)))
val layout = planGlueLayout(model(drawables, listOf(glue)))
val attributesA = layout.attributesById.getValue(DrawableId("a"))
val attributesB = layout.attributesById.getValue(DrawableId("b"))
// a's vertex 1 -> b's vertex 2, which is GLOBAL index 4 + 2 = 6.
assertEquals(6, attributesA.partnerIndex[1], "A's seam vertex points at B's, by global index")
assertEquals(0, attributesA.glueIndex[1])
assertEquals(0.25f, attributesA.weldWeight[1], "A carries weightA")
// b's vertex 2 -> a's vertex 1, global index 0 + 1 = 1.
assertEquals(1, attributesB.partnerIndex[2], "B's seam vertex points back at A's")
assertEquals(0, attributesB.glueIndex[2])
assertEquals(0.75f, attributesB.weldWeight[2], "B carries weightB")
// Untouched vertices stay no-op welds.
assertEquals(-1, attributesA.glueIndex[0])
assertEquals(-1, attributesB.glueIndex[3])
}
@Test
fun planGlueLayoutGivesAnIndexLessAnchorItsOwnRegion() {
// A zero-triangle anchor draws nothing but is a weld partner, so it MUST still get a region: pass 1
// deforms it, and pass 2 reads its positions. Dropping it would weld against uninitialised memory.
val anchor = drawable("anchor", 4).let { Drawable(it.id, it.name, null, BlendMode.Normal, emptyList(), it.mesh, it.geometryGrid) }
val drawables = listOf(anchor, drawable("b", 2))
val glue = Glue(DrawableId("anchor"), DrawableId("b"), listOf(GluePair(0, 0, 0f, 1f)))
val layout = planGlueLayout(model(drawables, listOf(glue)))
assertEquals(0, layout.baseOffsetById[DrawableId("anchor")])
assertEquals(4, layout.baseOffsetById[DrawableId("b")], "the anchor's 4 vertices still occupy the store")
assertEquals(6, layout.globalVertexCount)
assertEquals(4, layout.attributesById.getValue(DrawableId("anchor")).partnerIndex.size)
}
@Test
fun planGlueLayoutTagsEachGlueWithItsOwnIndex() {
// The glue index selects the per-pose intensity uniform, so a second glue must not reuse the first's.
val drawables = listOf(drawable("a", 2), drawable("b", 2), drawable("c", 2))
val glues =
listOf(
Glue(DrawableId("a"), DrawableId("b"), listOf(GluePair(0, 0, 0.5f, 0.5f))),
Glue(DrawableId("b"), DrawableId("c"), listOf(GluePair(1, 1, 0.5f, 0.5f))),
)
val layout = planGlueLayout(model(drawables, glues))
val attributesB = layout.attributesById.getValue(DrawableId("b"))
assertEquals(0, attributesB.glueIndex[0], "B's vertex 0 belongs to the first glue")
assertEquals(1, attributesB.glueIndex[1], "B's vertex 1 belongs to the second")
}
@Test
fun planGlueLayoutSkipsAGlueNamingAnAbsentDrawable() {
val drawables = listOf(drawable("a", 2))
val glue = Glue(DrawableId("a"), DrawableId("ghost"), listOf(GluePair(0, 0, 0.5f, 0.5f)))
val layout = planGlueLayout(model(drawables, listOf(glue)))
// "ghost" is named by the glue but carried by no drawable, so it gets no region and no attributes,
// and the pair is dropped rather than welding against a region that does not exist.
assertEquals(null, layout.baseOffsetById[DrawableId("ghost")])
assertEquals(2, layout.globalVertexCount, "only the real mesh occupies the store")
assertEquals(-1, layout.attributesById.getValue(DrawableId("a")).glueIndex[0], "the half-resolved pair is not applied")
}
@Test
fun planGlueLayoutLeavesGlueBeyondTheShaderArrayUnwelded() {
// The shader's glueIntensity[] uniform has exactly MAX_GLUES slots; a vertex tagged with glue index
// >= MAX_GLUES would read it out of bounds. Those pairs must stay -1 (unwelded), which is what makes
// resolvePose's "renders unwelded" promise true rather than an out-of-bounds read.
val a = drawable("a", 1)
val b = drawable("b", 1)
// MAX_GLUES + 1 glues, all on the same pair. The first MAX_GLUES tag vertex 0; the last must not.
val glues = List(MAX_GLUES + 1) { Glue(DrawableId("a"), DrawableId("b"), listOf(GluePair(0, 0, 0.5f, 0.5f))) }
val layout = planGlueLayout(model(listOf(a, b), glues))
// Each pair overwrites vertex 0's tag, so after the loop it holds the LAST in-bounds glue index.
assertEquals(MAX_GLUES - 1, layout.attributesById.getValue(DrawableId("a")).glueIndex[0], "the last addressable glue tags the vertex")
assertTrue(
layout.attributesById.getValue(DrawableId("a")).glueIndex.all { it < MAX_GLUES },
"no vertex is ever tagged with a glue index the shader array cannot hold",
)
}
}
@@ -0,0 +1,219 @@
package org.umamo.render.puppet
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
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.PuppetModel
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertIs
import kotlin.test.assertNull
import kotlin.test.assertSame
import kotlin.test.assertTrue
/**
* Pins [diffModel]'s four tiers by DECISION.
*
* The three GL reconcile tests cover this ground too, but they test the diff AND the GL apply together
* and assert on pixels - so they need a display, and they cover maybe half the cases. These enumerate the
* decisions themselves and run anywhere.
*/
class ModelDiffTest {
private val paramA = ParameterId("A")
private fun grid(positions: FloatArray): KeyformGrid<MeshDeltaForm> =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0f))),
listOf(KeyformCell(intArrayOf(0), MeshDeltaForm(FloatArray(positions.size)))),
)
private fun drawable(
id: String,
positions: FloatArray,
uvs: FloatArray = FloatArray(positions.size),
indices: IntArray = intArrayOf(0, 1, 2),
keyforms: KeyformGrid<MeshDeltaForm>? = null,
): Drawable =
Drawable(
id = DrawableId(id),
name = id,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(positions, uvs, indices),
geometryGrid = keyforms ?: grid(positions),
)
private fun model(vararg drawables: Drawable): PuppetModel =
PuppetModel(
parameters = listOf(Parameter(paramA, "A", -1f, 1f, 0f)),
parts = emptyList(),
deformers = emptyList(),
drawables = drawables.toList(),
rootChildren = drawables.map { OrgChild.Drawable(it.id) },
rootPartId = null,
canvasWidth = 0f,
canvasHeight = 0f,
worldOriginX = 0f,
worldOriginZ = 0f,
)
private fun resident(vararg pairs: Pair<String, Int>): Map<DrawableId, Int> = pairs.associate { DrawableId(it.first) to it.second }
@Test
fun diffModelKeepsAnUntouchedDrawableWithNoWork() {
// Copy-on-write means an untouched drawable keeps its array instances, so both tiers are null and
// the backend does nothing at all - the case that must stay cheap, since it is every frame's.
val source = drawable("a", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f))
val diff = diffModel(model(source), model(source), resident("a" to 3))
val keep = assertIs<DrawableAction.Keep>(diff.actions.single())
assertNull(keep.positions, "an untouched mesh re-uploads no positions")
assertNull(keep.uvs, "and no UVs")
assertTrue(diff.removed.isEmpty())
}
@Test
fun diffModelUploadsADrawableTheBackendHasNeverSeen() {
val existing = drawable("a", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f))
val added = drawable("copy", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f))
// "copy" is absent from the resident map - an Object-mode duplicate, or one skipped at load.
val diff = diffModel(model(existing), model(existing, added), resident("a" to 3))
val upload = assertIs<DrawableAction.Upload>(diff.actions[1])
assertEquals(DrawableId("copy"), upload.drawableId)
assertTrue(diff.removed.isEmpty())
}
@Test
fun diffModelRemovesAResidentTheEditDropped() {
val kept = drawable("a", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f))
val dropped = drawable("gone", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f))
val diff = diffModel(model(kept, dropped), model(kept), resident("a" to 3, "gone" to 3))
assertEquals(listOf(DrawableId("gone")), diff.removed)
}
@Test
fun diffModelReuploadsOnEachTopologyTrigger() {
val positions = floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f)
val before = drawable("a", positions)
// 1. The vertex count changed against what the backend uploaded.
val grown = drawable("a", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f, 2f, 2f))
assertIs<DrawableAction.Reupload>(diffModel(model(before), model(grown), resident("a" to 3)).actions.single(), "vertex count")
// 2. The indices array instance changed (a merge / rip / connect).
val reindexed = drawable("a", positions, indices = intArrayOf(0, 2, 1))
assertIs<DrawableAction.Reupload>(diffModel(model(before), model(reindexed), resident("a" to 3)).actions.single(), "indices")
// 3. The keyform grid instance changed, so the delta texture's striding is stale.
val rekeyed = drawable("a", positions, keyforms = grid(positions))
assertIs<DrawableAction.Reupload>(diffModel(model(before), model(rekeyed), resident("a" to 3)).actions.single(), "keyforms")
}
@Test
fun diffModelReuploadsPositionsOnlyWhenTheArrayInstanceChanged() {
val before = drawable("a", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f))
val movedPositions = floatArrayOf(5f, 5f, 6f, 5f, 6f, 6f)
// withMeshPositions shares the uvs array by reference; only positions is a new instance.
val after = drawable("a", movedPositions, uvs = before.mesh!!.uvs, indices = before.mesh!!.indices, keyforms = before.geometryGrid)
val keep = assertIs<DrawableAction.Keep>(diffModel(model(before), model(after), resident("a" to 3)).actions.single())
assertSame(movedPositions, keep.positions, "the moved positions re-upload")
assertNull(keep.uvs, "the shared uvs array does not")
}
@Test
fun diffModelReuploadsUvsOnlyWhenTheArrayInstanceChanged() {
val before = drawable("a", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f))
val movedUvs = floatArrayOf(0.5f, 0.5f, 1f, 0.5f, 1f, 1f)
val after =
drawable("a", before.mesh!!.positions, uvs = movedUvs, indices = before.mesh!!.indices, keyforms = before.geometryGrid)
val keep = assertIs<DrawableAction.Keep>(diffModel(model(before), model(after), resident("a" to 3)).actions.single())
assertNull(keep.positions)
assertSame(movedUvs, keep.uvs, "a UV edit re-uploads the UV buffer only")
}
@Test
fun diffModelSkipsUvsWhoseLengthDisagreesWithTheResident() {
// Defensive: the copy-on-write UV edit never changes the length, so a mismatch means the backend
// padded this mesh's UVs at upload. Re-uploading a short array would leave the tail stale.
val before = drawable("a", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f), uvs = FloatArray(6))
val after = drawable("a", before.mesh!!.positions, uvs = FloatArray(2), indices = before.mesh!!.indices, keyforms = before.geometryGrid)
val keep = assertIs<DrawableAction.Keep>(diffModel(model(before), model(after), resident("a" to 3)).actions.single())
assertNull(keep.uvs, "a length mismatch leaves the resident's UVs alone")
}
@Test
fun diffModelNeverBothActionsAndRemovesTheSameDrawable() {
// The double-free guard. A remesh frees the resident and re-uploads; if that upload yields nothing
// (a remesh to zero triangles), the drawable must NOT also appear in `removed` - freeing the same GL
// names twice can hit a name the driver recycled for a later upload in the same pass, which would
// free a live buffer belonging to a different drawable.
val before = drawable("a", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f))
val emptied = drawable("a", floatArrayOf(0f, 0f), indices = IntArray(0))
val diff = diffModel(model(before), model(emptied), resident("a" to 3))
assertIs<DrawableAction.Reupload>(diff.actions.single())
assertTrue(diff.removed.isEmpty(), "a re-uploaded drawable is never also removed")
}
@Test
fun diffModelKeepsResidentWhoseMeshWentNull() {
// Reachable: a kept resident whose new mesh is null. The resident vertex count must come from the
// backend, not the model, because the model no longer carries what the buffers were built at.
val before = drawable("a", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f))
val meshless =
Drawable(DrawableId("a"), "a", null, BlendMode.Normal, emptyList(), mesh = null, geometryGrid = before.geometryGrid)
val diff = diffModel(model(before), model(meshless), resident("a" to 3))
val keep = assertIs<DrawableAction.Keep>(diff.actions.single())
assertNull(keep.positions)
assertNull(keep.uvs)
assertTrue(diff.removed.isEmpty(), "it stays resident rather than being freed")
}
@Test
fun diffModelActionsFollowNewModelOrderThroughAReorder() {
// Keyed by id, so a simultaneous reorder is handled; the actions follow the NEW order, which is what
// rebuilds residency in that order.
val first = drawable("a", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f))
val second = drawable("b", floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f))
val diff = diffModel(model(first, second), model(second, first), resident("a" to 3, "b" to 3))
assertEquals(listOf(DrawableId("b"), DrawableId("a")), diff.actions.map { it.drawableId })
assertTrue(diff.actions.all { it is DrawableAction.Keep }, "a reorder needs no buffer work")
assertTrue(diff.removed.isEmpty())
}
@Test
fun diffModelReuploadsWhenWarpParentingFlips() {
// A drawable owns a control-point texture iff its parent is a warp, and that is fixed at upload. A
// reparent that flips it (deleting a rotation deformer between a drawable and a warp, so the drawable
// now parents the warp directly) must Reupload, or the resident keeps a stale / absent cp texture and
// the shader samples whatever texture unit 3 last held. Keying purely on the two models' warp sets.
val positions = floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f)
val warp = Deformer.Warp(DeformerId("warp"), "warp", parent = null, partId = null, rows = 2, columns = 2, isQuadTransform = true, geometryGrid = null)
val rotation = Deformer.Rotation(DeformerId("rot"), "rot", parent = null, partId = null, baseAngle = 0f, geometryGrid = null)
val rotationParented = drawable("a", positions).copy(parentDeformerId = DeformerId("rot"))
val warpParented = rotationParented.copy(parentDeformerId = DeformerId("warp"))
// Non-warp parent → warp parent: gains a cp texture, so Reupload.
val gained = diffModel(modelOf(listOf(rotation, warp), rotationParented), modelOf(listOf(rotation, warp), warpParented), resident("a" to 3))
assertIs<DrawableAction.Reupload>(gained.actions.single(), "warp parenting gained")
// Warp parent → non-warp parent: loses the cp texture, so Reupload.
val lost = diffModel(modelOf(listOf(rotation, warp), warpParented), modelOf(listOf(rotation, warp), rotationParented), resident("a" to 3))
assertIs<DrawableAction.Reupload>(lost.actions.single(), "warp parenting lost")
// Warp parent → SAME warp parent (a mere reorder around it): control-point ownership unchanged, so Keep.
val unchanged = diffModel(modelOf(listOf(rotation, warp), warpParented), modelOf(listOf(rotation, warp), warpParented), resident("a" to 3))
assertIs<DrawableAction.Keep>(unchanged.actions.single(), "unchanged warp parent needs no re-upload")
}
/** A model with explicit deformers - the plain [model] helper carries none, which the warp cases need. */
private fun modelOf(deformers: List<Deformer>, vararg drawables: Drawable): PuppetModel =
model(*drawables).copy(deformers = deformers)
}
@@ -0,0 +1,48 @@
package org.umamo.render.puppet
import kotlin.test.Test
import kotlin.test.assertContentEquals
import kotlin.test.assertEquals
/**
* Pins [flipRowsVertically] - the bottom-up-read-back to top-first conversion. Tiny, but it is the one
* place the framebuffer Y convention is decided, and getting it backwards silently mirrors every dump.
*/
class PixelRowsTest {
/** One opaque RGBA pixel, so a row's identity is readable at the call site. */
private fun pixel(red: Int, green: Int, blue: Int): ByteArray = byteArrayOf(red.toByte(), green.toByte(), blue.toByte(), 255.toByte())
private val redRow = pixel(255, 0, 0)
private val greenRow = pixel(0, 255, 0)
@Test
fun flipRowsVerticallyReversesRowOrder() {
val flipped = flipRowsVertically(redRow + greenRow, width = 1, height = 2)
assertContentEquals(greenRow + redRow, flipped, "the bottom (green) row must come first after the flip")
}
@Test
fun flipRowsVerticallyKeepsChannelOrderWithinAPixel() {
// Row-wise, not per-pixel: RGBA must survive untouched, only the rows move.
val singleRow = pixel(1, 2, 3) + pixel(4, 5, 6)
assertContentEquals(singleRow, flipRowsVertically(singleRow, width = 2, height = 1), "a single row is unchanged, channels included")
}
@Test
fun flipRowsVerticallyIsItsOwnInverse() {
val original = redRow + greenRow
assertContentEquals(original, flipRowsVertically(flipRowsVertically(original, 1, 2), 1, 2), "flipping twice returns the original")
}
@Test
fun flipRowsVerticallyMovesWholeRowsNotPixels() {
// Rows are [A B] then [C D]; the flip must yield [C D] then [A B], NOT a reversal of the whole
// buffer (which would give [D C] [B A]) - the classic way to get this wrong.
val topRow = pixel(10, 10, 10) + pixel(20, 20, 20)
val bottomRow = pixel(30, 30, 30) + pixel(40, 40, 40)
val flipped = flipRowsVertically(topRow + bottomRow, width = 2, height = 2)
assertContentEquals(bottomRow + topRow, flipped, "whole rows swap, pixel order within each row intact")
assertEquals(30, flipped[0], "the bottom row's first pixel leads after the flip")
assertEquals(40, flipped[4], "and its second pixel stays second within that row")
}
}
@@ -0,0 +1,238 @@
package org.umamo.render.puppet
import org.umamo.render.eval.RenderPlanComposite
import org.umamo.render.eval.RenderPlanDrawable
import org.umamo.render.eval.flattenRenderPlan
import org.umamo.render.eval.preparePose
import org.umamo.render.glsl.MAX_GLUES
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.DEFAULT_DRAW_ORDER
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.Glue
import org.umamo.runtime.model.GluePair
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.PartComposite
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RenderDrawable
import org.umamo.runtime.model.RenderGroup
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertIs
import kotlin.test.assertTrue
/**
* Pins [resolvePose]: the posed-vs-drawn distinction, the drawn filter, and the glue both-posed gate.
*
* The gate had no coverage anywhere before this - not CPU, not GPU. It is the rule that stops a weld
* reading a partner's uninitialised region of the shared position store, which on a live GPU shows up as
* random geometry spikes while a parameter moves, so it is worth pinning precisely.
*/
class PoseResolveTest {
private val paramA = ParameterId("A")
private fun drawable(id: String, indices: IntArray = intArrayOf(0, 1, 2)): Drawable {
val positions = floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f)
return Drawable(
id = DrawableId(id),
name = id,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(positions, FloatArray(positions.size), indices),
geometryGrid =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0f))),
listOf(KeyformCell(intArrayOf(0), MeshDeltaForm(FloatArray(positions.size)))),
),
)
}
private fun model(drawables: List<Drawable>, glues: List<Glue> = emptyList()): PuppetModel =
PuppetModel(
parameters = listOf(Parameter(paramA, "A", -1f, 1f, 0f)),
parts = emptyList(),
deformers = emptyList(),
drawables = drawables,
rootChildren = drawables.map { OrgChild.Drawable(it.id) },
rootPartId = null,
glues = glues,
canvasWidth = 0f,
canvasHeight = 0f,
worldOriginX = 0f,
worldOriginZ = 0f,
)
private fun resolve(
source: PuppetModel,
renderable: Map<DrawableId, Boolean>,
shown: Set<DrawableId> = source.drawables.map { it.id }.toSet(),
renderRoot: RenderGroup = RenderGroup(null, DEFAULT_DRAW_ORDER, emptyList()),
) = resolvePose(
inputs = preparePose(source, emptyMap()),
renderableById = renderable,
shownIds = shown,
baseOrder = source.drawables.map { it.id },
renderRoot = renderRoot,
glueIntensities = FloatArray(MAX_GLUES) { 1f },
)
@Test
fun resolvePoseDrawsOnlyResidentRenderableShownDrawables() {
val source = model(listOf(drawable("a"), drawable("b"), drawable("hidden")))
val resolved =
resolve(
source,
renderable = mapOf(DrawableId("a") to true, DrawableId("b") to true, DrawableId("hidden") to true),
shown = setOf(DrawableId("a"), DrawableId("b")),
)
assertEquals(listOf(DrawableId("a"), DrawableId("b")), resolved.drawOrder, "the hidden drawable is not drawn")
assertTrue(DrawableId("hidden") in resolved.posed, "but it still POSES - it may be a mask source")
}
@Test
fun resolvePosePosesAnIndexLessAnchorButDoesNotDrawIt() {
// The posed-vs-drawn distinction. An index-less glue anchor must deform (pass 1 writes its positions
// for a partner to weld against) while drawing nothing. Conflating the two breaks glue silently.
val source = model(listOf(drawable("anchor", indices = IntArray(0)), drawable("b")))
val resolved = resolve(source, renderable = mapOf(DrawableId("anchor") to false, DrawableId("b") to true))
assertTrue(
DrawableId("anchor") in resolved.posed,
"the anchor poses: its deformed positions are a weld partner",
)
assertEquals(listOf(DrawableId("b")), resolved.drawOrder, "but it draws nothing")
}
@Test
fun resolvePoseSkipsADrawableTheBackendNeverUploaded() {
val source = model(listOf(drawable("a"), drawable("absent")))
val resolved = resolve(source, renderable = mapOf(DrawableId("a") to true))
assertTrue(DrawableId("absent") !in resolved.posed, "a non-resident drawable cannot pose")
assertEquals(listOf(DrawableId("a")), resolved.drawOrder)
}
@Test
fun resolvePoseGlueIntensityHoldsWhenBothMeshesPose() {
val source =
model(
listOf(drawable("a"), drawable("b")),
listOf(Glue(DrawableId("a"), DrawableId("b"), listOf(GluePair(0, 0, 0.5f, 0.5f)))),
)
val resolved = resolve(source, renderable = mapOf(DrawableId("a") to true, DrawableId("b") to true))
assertEquals(1f, resolved.glueIntensities[0], "both posed, so the weld runs at full intensity")
}
@Test
fun resolvePoseZeroesGlueIntensityWhenAPartnerIsUnposed() {
// The gate. "b" is not resident, so pass 1 never writes its region of the shared store; welding
// toward it would read uninitialised memory. Zeroing makes the shader skip the partner read entirely.
val source =
model(
listOf(drawable("a"), drawable("b")),
listOf(Glue(DrawableId("a"), DrawableId("b"), listOf(GluePair(0, 0, 0.5f, 0.5f)))),
)
val resolved = resolve(source, renderable = mapOf(DrawableId("a") to true))
assertEquals(0f, resolved.glueIntensities[0], "an unposed partner disables the weld")
}
@Test
fun resolvePoseGateAsksWhetherThePartnerPosedNotWhetherItDraws() {
// An index-less anchor draws nothing yet is a perfectly good partner: it poses, so the weld holds.
// Gating on "draws" instead of "poses" would silently disable every anchor-based glue.
val source =
model(
listOf(drawable("anchor", indices = IntArray(0)), drawable("b")),
listOf(Glue(DrawableId("anchor"), DrawableId("b"), listOf(GluePair(0, 0, 0f, 1f)))),
)
val resolved = resolve(source, renderable = mapOf(DrawableId("anchor") to false, DrawableId("b") to true))
assertEquals(1f, resolved.glueIntensities[0], "a non-drawing anchor still counts as posed")
}
@Test
fun resolvePoseKeepsIsolatedBoundariesInThePlanAndFlattensToDrawOrder() {
val source = model(listOf(drawable("a"), drawable("b")))
val isolatedRoot =
RenderGroup(
partId = null,
drawOrder = DEFAULT_DRAW_ORDER,
children =
listOf(
RenderDrawable(DrawableId("b")),
RenderGroup(
PartId("fx"),
600,
listOf(RenderDrawable(DrawableId("a"))),
ChannelGrids.Empty,
PartComposite(),
),
),
)
val resolved =
resolve(
source,
renderable = mapOf(DrawableId("a") to true, DrawableId("b") to true),
renderRoot = isolatedRoot,
)
assertEquals(2, resolved.renderPlan.size)
assertEquals(DrawableId("b"), assertIs<RenderPlanDrawable>(resolved.renderPlan[0]).id)
val compositeNode = assertIs<RenderPlanComposite>(resolved.renderPlan[1])
assertEquals(PartId("fx"), compositeNode.partId)
assertEquals(flattenRenderPlan(resolved.renderPlan), resolved.drawOrder, "the flat order IS the plan flattened")
assertEquals(listOf(DrawableId("b"), DrawableId("a")), resolved.drawOrder)
}
@Test
fun resolvePoseDropsACompositeNodeWhoseSubtreeFilteredAway() {
// The isolated part's only drawable is hidden → its whole composite disappears (an empty
// buffer composite would be a wasted pass); the flat order agrees.
val source = model(listOf(drawable("a"), drawable("b")))
val isolatedRoot =
RenderGroup(
partId = null,
drawOrder = DEFAULT_DRAW_ORDER,
children =
listOf(
RenderDrawable(DrawableId("b")),
RenderGroup(
PartId("fx"),
600,
listOf(RenderDrawable(DrawableId("a"))),
ChannelGrids.Empty,
PartComposite(),
),
),
)
val resolved =
resolve(
source,
renderable = mapOf(DrawableId("a") to true, DrawableId("b") to true),
shown = setOf(DrawableId("b")),
renderRoot = isolatedRoot,
)
assertEquals(1, resolved.renderPlan.size, "the empty composite node is dropped")
assertEquals(DrawableId("b"), assertIs<RenderPlanDrawable>(resolved.renderPlan.single()).id)
assertEquals(listOf(DrawableId("b")), resolved.drawOrder)
}
@Test
fun resolvePoseGlueIntensitiesBeyondTheShaderArrayAreDropped() {
// MAX_GLUES is a shader contract (uniform float glueIntensity[MAX_GLUES]), not a tuning knob: glue
// #65+ renders UNWELDED rather than overrunning the array. Pinned so the ceiling is not "fixed" by
// growing the Kotlin side alone, which would silently disagree with the GLSL.
val drawables = listOf(drawable("a"), drawable("b"))
val glues = List(70) { Glue(DrawableId("a"), DrawableId("b"), listOf(GluePair(0, 0, 0.5f, 0.5f))) }
val resolved =
resolve(model(drawables, glues), renderable = mapOf(DrawableId("a") to true, DrawableId("b") to true))
assertEquals(64, resolved.glueIntensities.size, "the array is exactly the shader's")
assertEquals(1f, resolved.glueIntensities[63], "the last addressable glue resolves")
}
}
@@ -0,0 +1,132 @@
package org.umamo.render.puppet
import org.umamo.render.eval.MeshBlendContribution
import org.umamo.render.eval.MeshBlendState
import org.umamo.render.eval.RotationWorld
import org.umamo.render.eval.WarpWorld
import org.umamo.render.eval.rotationXform
import org.umamo.render.eval.warpApply
import org.umamo.runtime.eval.WeightedCell
import org.umamo.runtime.eval.cellsByLinearIndex
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.MeshForm
import org.umamo.runtime.model.ParameterId
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* Pins [deformedWorldBounds] - the exact deformed-world AABB the composite scissor is built from.
* The contract is that the bound equals the true deformed geometry (min/max of the exact deform), so
* the scissor never clips: every case here rebuilds the deform independently and asserts equality,
* including a warp vertex OUTSIDE the lattice (the extrapolation case a cheap analytic bound
* undersized, clipping heads and arm tips). Pure math, no GPU.
*/
class PosedBoundsTest {
private val paramA = ParameterId("A")
/** A one-cell grid over [base]'s vertex count, whose single cell holds [deltas]. */
private fun oneCellCells(deltas: FloatArray): Map<Int, KeyformCell<MeshDeltaForm>> {
val grid =
KeyformGrid(
listOf(KeyformAxis(paramA, floatArrayOf(0f))),
listOf(KeyformCell(intArrayOf(0), MeshDeltaForm(deltas))),
)
return cellsByLinearIndex(grid)
}
private val fullCorner = listOf(WeightedCell(0, 1f))
@Test
fun directMeshBlendsCornersAndNegatesY() {
// base (1,2)(3,5) + cell delta (10,0)(0,0) -> local (11,2)(3,5) -> Y-negate (11,-2)(3,-5).
val base = floatArrayOf(1f, 2f, 3f, 5f)
val cells = oneCellCells(floatArrayOf(10f, 0f, 0f, 0f))
val bounds = deformedWorldBounds(base, cells, fullCorner, parentWorld = null, blend = null)!!
assertEquals(3f, bounds.minX)
assertEquals(11f, bounds.maxX)
assertEquals(-5f, bounds.minY)
assertEquals(-2f, bounds.maxY)
}
@Test
fun blendShapeDeltasWidenTheBound() {
// One vertex, zero grid delta, a blend contribution of (+4, +6) at weight 0.5 relative to a
// (+1, +2) reference -> local (0,0) + 0.5*((4,6)-(1,2)) = (1.5, 2) -> Y-negate (1.5, -2).
val base = floatArrayOf(0f, 0f)
val cells = oneCellCells(floatArrayOf(0f, 0f))
val blend =
MeshBlendState(
contributions = listOf(MeshBlendContribution(bindingIndex = 0, keyIndex = 0, form = MeshForm(floatArrayOf(4f, 6f)), weight = 0.5f)),
referenceDeltas = floatArrayOf(1f, 2f),
referenceDrawOrder = 0f,
referenceOpacity = 1f,
)
val bounds = deformedWorldBounds(base, cells, fullCorner, parentWorld = null, blend = blend)!!
assertClose(1.5f, bounds.minX)
assertClose(1.5f, bounds.maxX)
assertClose(-2f, bounds.minY)
assertClose(-2f, bounds.maxY)
}
@Test
fun rotationParentTransformsExactly() {
// A 90-degree rotation about the origin maps (x, y) -> (-y, x) before the Y-negate; a box
// [1,3]x[0,2] -> corners approx (0,1)(0,3)(-2,1)(-2,3) -> x[-2,0], y[1,3] -> Y-negate y[-3,-1].
val rotation = RotationWorld(rotationXform(90f, 1f, flipX = false, flipY = false, ox = 0f, oy = 0f), accY = 1f)
val base = floatArrayOf(1f, 0f, 3f, 0f, 1f, 2f, 3f, 2f)
val cells = oneCellCells(FloatArray(8))
val bounds = deformedWorldBounds(base, cells, fullCorner, parentWorld = rotation, blend = null)!!
assertClose(-2f, bounds.minX)
assertClose(0f, bounds.maxX)
assertClose(-3f, bounds.minY)
assertClose(-1f, bounds.maxY)
}
@Test
fun warpParentInGridMatchesTheLattice() {
// A 1x1 bilinear lattice mapping the unit square to world [10,20]x[30,50]; the unit-square mesh
// recovers that rect, Y-negated.
val warp = WarpWorld(floatArrayOf(10f, 30f, 20f, 30f, 10f, 50f, 20f, 50f), cols = 1, rows = 1, bilinear = true, accY = 1f)
val base = floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f, 1f, 1f)
val cells = oneCellCells(FloatArray(8))
val bounds = deformedWorldBounds(base, cells, fullCorner, parentWorld = warp, blend = null)!!
assertClose(10f, bounds.minX)
assertClose(20f, bounds.maxX)
assertClose(-50f, bounds.minY)
assertClose(-30f, bounds.maxY)
}
@Test
fun warpParentExtrapolatedVertexMatchesWarpApply() {
// The case a cheap analytic bound got wrong: a vertex OUTSIDE the lattice (u = 1.5). The exact
// bound must equal warpApply itself - not an undersized approximation that would clip the vertex.
val cp = floatArrayOf(10f, 30f, 20f, 30f, 10f, 50f, 20f, 50f)
val warp = WarpWorld(cp, cols = 1, rows = 1, bilinear = true, accY = 1f)
val expected = FloatArray(2)
warpApply(cp, 1, 1, true, 1.5f, 0.5f, expected, 0)
val bounds = deformedWorldBounds(floatArrayOf(1.5f, 0.5f), oneCellCells(floatArrayOf(0f, 0f)), fullCorner, parentWorld = warp, blend = null)!!
// One vertex, so min == max == the exact warp image, Y-negated.
assertClose(expected[0], bounds.minX)
assertClose(expected[0], bounds.maxX)
assertClose(-expected[1], bounds.minY)
assertClose(-expected[1], bounds.maxY)
}
@Test
fun unionBoundsCoversBoth() {
val union = unionBounds(PosedAabb(0f, 0f, 2f, 2f), PosedAabb(-1f, 3f, 1f, 5f))
assertEquals(-1f, union.minX)
assertEquals(0f, union.minY)
assertEquals(2f, union.maxX)
assertEquals(5f, union.maxY)
}
private fun assertClose(expected: Float, actual: Float) {
assertTrue(abs(expected - actual) < 1e-3f, "expected ~$expected, got $actual")
}
}
@@ -0,0 +1,146 @@
package org.umamo.render.metal
import org.umamo.format.raster.RasterImage
import org.umamo.render.device.DeformCapturePipeline
import org.umamo.render.device.DeformedPositionStore
import org.umamo.render.device.FrameEncoder
import org.umamo.render.device.GpuMesh
import org.umamo.render.device.GpuTexture
import org.umamo.render.device.MeshSpec
import org.umamo.render.device.ReadbackTicket
import org.umamo.render.device.RenderDevice
import org.umamo.render.device.RenderPipeline
import org.umamo.render.device.RenderPipelineSpec
import org.umamo.render.device.RenderTarget
import org.umamo.render.device.RenderTargetSpec
import org.umamo.render.device.ScissorRect
import org.umamo.render.device.TextureFilter
import org.umamo.render.device.TextureFormat
import org.umamo.render.device.TextureWrap
/**
* The iPadOS Metal [RenderDevice] - a STUB marking the port's entry point; nothing is implemented.
*
* Implementing this ONE interface is the whole port: `PuppetRenderer` and everything it stands on
* (the deform eval, pose resolution, glue planning, model diff) are backend-neutral commonMain and
* come along for free. Kotlin/Native reaches Metal directly via `platform.Metal`; a Swift-side
* implementation bridged through this interface works too.
*
* What is genuinely different from the GL device, decided up front so the port does not rediscover it:
* - Shaders are MSL, keyed by [RenderPipelineSpec.purpose] - the GLSL in `org.umamo.render.glsl` is a
* GL-family asset and none of it is reused. The fidelity-critical piece is `deformWorld`
* (DeformGlsl.kt): ~200 lines whose `warpExtrap` lattice extrapolation silently breaks rig fidelity
* if mistranslated. Build the MSL equivalent of `GpuDeformValidationTest` (the GPU-vs-CPU oracle;
* the CPU side is commonMain and already available here) BEFORE trusting the translation - and the
* glue equivalent of `GpuGlueValidationTest` alongside it.
* - [createDeformCapturePipeline] / the capture pass: Metal has no transform feedback - a compute
* kernel reads base positions + the delta texture and writes the store, which is naturally a
* `device float2*` buffer here rather than any texture.
* - [FrameEncoder.barrier] is a GENUINE no-op: Metal orders encoder-to-encoder resource dependencies
* within a command buffer itself. Correct, not a stub - do not add a wait.
* - Blend is baked into the MTLRenderPipelineState per [RenderPipelineSpec] (the API is already shaped
* for that); `LoadAction`/`StoreAction` map 1:1 onto MTLRenderPassDescriptor and are real wins on a
* tile-based GPU (the grid pass is DontCare - the tile is never fetched).
* - [readPixels] returns TOP row first per the API contract. Metal's origin is already top-left, so
* unlike the GL device there is NO row flip here.
* - Two conventions inside the shaders are CONTENT, not backend, and must be kept verbatim in MSL:
* `deformWorld`'s final Y negation (the CMO3 Y-down → Umamo Y-up format convention) and the atlas
* page quad's V-flip (Y-up display vs top-first atlas rows). "Correcting" either for Metal's
* texture origin inverts the rig or the page.
* - The mask pass and the main pass must share one screen-space convention (the fragment position the
* coverage lookup divides by viewport size) - self-consistent per backend, silently wrong if only
* one pass is flipped. Worst on masked warp meshes, which draw twice.
* - The uniform structs ([org.umamo.render.device.DeformUniforms] etc.) are MUTABLE AND REUSED per
* draw: marshal every field before returning (`setVertexBytes` copies, so that is natural) and
* never retain the instance.
*/
class MetalRenderDevice : RenderDevice {
override fun createTexture(
width: Int,
height: Int,
format: TextureFormat,
filter: TextureFilter,
pixels: ByteArray?,
wrap: TextureWrap,
): GpuTexture =
TODO(
"Metal port: MTLTexture (RGBA8Unorm / RG32Float), top-first upload needs no flip; wrap is the " +
"sampler's addressMode - clampToEdge or clampToZero, and a sampler is per-texture here",
)
override fun createFloatTexture(width: Int, height: Int, filter: TextureFilter, texels: FloatArray): GpuTexture =
TODO("Metal port: RG32Float MTLTexture")
override fun updateFloatTexture(texture: GpuTexture, width: Int, height: Int, texels: FloatArray): Unit =
TODO("Metal port: replaceRegion in place (keep the once-per-pose contract)")
override fun createMesh(spec: MeshSpec): GpuMesh =
TODO("Metal port: MTLBuffers; vertex layout lives in the pipeline descriptor, not the mesh")
override fun updateMeshPositions(mesh: GpuMesh, restPositions: FloatArray): Unit = TODO("Metal port")
override fun updateMeshUvs(mesh: GpuMesh, uvs: FloatArray): Unit = TODO("Metal port")
override fun createRenderTarget(spec: RenderTargetSpec): RenderTarget =
TODO("Metal port: MTLTexture with usage renderTarget (+ shaderRead when spec.sampled)")
override fun createDeformedPositionStore(vertexCapacity: Int): DeformedPositionStore =
TODO("Metal port: a device float2* MTLBuffer - no texture indirection needed here")
override fun createRenderPipeline(spec: RenderPipelineSpec): RenderPipeline =
TODO("Metal port: MTLRenderPipelineState from the MSL library, keyed by spec.purpose, blend baked per spec.blend")
override fun createDeformCapturePipeline(): DeformCapturePipeline =
TODO("Metal port: a compute pipeline - Metal has no transform feedback; see the class docblock")
override fun destroyTexture(texture: GpuTexture): Unit = TODO("Metal port")
override fun destroyMesh(mesh: GpuMesh): Unit = TODO("Metal port")
override fun destroyRenderTarget(target: RenderTarget): Unit = TODO("Metal port")
override fun beginFrame(): FrameEncoder =
TODO("Metal port: open a command buffer; passes are encoders; barrier() is a genuine no-op; endFrame commits")
override fun resolve(source: RenderTarget, destination: RenderTarget, region: ScissorRect?): Unit =
TODO(
"Metal port: region == null is the scaled full-surface downscale (a full-screen textured draw or " +
"MPSImageBilinearScale - NOT a blit encoder, which can neither filter nor scale); region != null is a " +
"same-size sub-rect copy (the composite snapshot), for which a plain MTLBlitCommandEncoder copy is exact.",
)
override fun resolveUsed(
source: RenderTarget,
sourceUsedWidth: Int,
sourceUsedHeight: Int,
destination: RenderTarget,
destinationUsedWidth: Int,
destinationUsedHeight: Int,
region: ScissorRect?,
): Unit =
TODO(
"Metal port: like resolve but over the used regions. Content anchors at Metal's TOP-LEFT origin, " +
"so the used region is the top-left rows and a non-null region needs no y conversion at all.",
)
override fun beginReadback(target: RenderTarget): ReadbackTicket =
TODO("Metal port: blit target into a shared-storage staging buffer, addCompletedHandler flags the ticket done")
override fun beginReadback(target: RenderTarget, usedWidth: Int, usedHeight: Int): ReadbackTicket =
TODO("Metal port: the full-target beginReadback over the top-left used region (no flip on this backend)")
override fun pollReadback(ticket: ReadbackTicket): RasterImage? =
TODO("Metal port: drain the completed flag ON THE POLL, so results arrive on the render thread whatever thread the handler ran on; top-first already, no row flip")
override fun cancelReadback(ticket: ReadbackTicket): Unit = TODO("Metal port")
override fun readPixels(target: RenderTarget): RasterImage =
TODO("Metal port: getBytes - already top-first, NO row flip (unlike the GL device)")
override fun readPixels(target: RenderTarget, usedWidth: Int, usedHeight: Int): RasterImage =
TODO("Metal port: the full-target readPixels over the top-left used region (no flip on this backend)")
override fun maxRenderTargetSize(): Int = TODO("Metal port: the device family's maximum 2D texture width (16384 on Apple GPU families 3 and up)")
override fun describeBackend(): String = TODO("Metal port: MTLDevice.name")
}
@@ -0,0 +1,397 @@
package org.umamo.render.gl
import org.lwjgl.BufferUtils
import org.lwjgl.opengl.GL11
import org.lwjgl.opengl.GL13
import org.lwjgl.opengl.GL14
import org.lwjgl.opengl.GL20
import org.lwjgl.opengl.GL30
import org.lwjgl.opengl.GL31
import org.umamo.render.device.AxisLineUniforms
import org.umamo.render.device.CompositeUniforms
import org.umamo.render.device.DeformCapturePassEncoder
import org.umamo.render.device.DeformCapturePipeline
import org.umamo.render.device.DeformUniforms
import org.umamo.render.device.DeformedPositionStore
import org.umamo.render.device.DrawTextures
import org.umamo.render.device.FragmentUniforms
import org.umamo.render.device.FrameEncoder
import org.umamo.render.device.GpuMesh
import org.umamo.render.device.GpuTexture
import org.umamo.render.device.GridUniforms
import org.umamo.render.device.LoadAction
import org.umamo.render.device.RenderPassEncoder
import org.umamo.render.device.RenderPassSpec
import org.umamo.render.device.RenderPipeline
import org.umamo.render.device.TextureFilter
import org.umamo.render.device.TextureWrap
import org.umamo.render.device.WorldToNdc
import org.umamo.render.glsl.UNIT_ATLAS
import org.umamo.render.glsl.UNIT_CP
import org.umamo.render.glsl.UNIT_DELTA
import org.umamo.render.glsl.UNIT_DEST
import org.umamo.render.glsl.UNIT_LAYER
import org.umamo.render.glsl.UNIT_MASK
import org.umamo.render.glsl.UNIT_POSITION
import java.nio.FloatBuffer
import java.nio.IntBuffer
/**
* The GL implementation of one frame's recorded work.
*
* GL has no command buffer, so "recording" is really "issuing immediately": each call runs against the
* current context as it arrives. The encoder shape still earns its keep - it names the target every pass
* writes and fixes each pipeline's blend up front, both of which read better than the ambient-state
* idiom - and it is what a Metal backend, which does have command buffers, would map onto directly.
*
* @param Int emptyVao A bound VAO for the attribute-less draws (grid, axis, atlas page); a core profile
* requires one even when the shader synthesises positions from gl_VertexID.
*/
internal class GlFrameEncoder(private val emptyVao: Int) : FrameEncoder {
override fun beginRenderPass(spec: RenderPassSpec): RenderPassEncoder {
val target = spec.colorTarget as GlRenderTarget
GL30.glBindFramebuffer(GL30.GL_FRAMEBUFFER, target.framebuffer)
GL11.glViewport(0, 0, spec.viewportWidth, spec.viewportHeight)
val scissor = spec.scissor
if (scissor != null) {
// The spec's rect is top-left-origin (the read-back convention); GL scissors bottom-up.
GL11.glEnable(GL11.GL_SCISSOR_TEST)
GL11.glScissor(scissor.x, spec.viewportHeight - scissor.y - scissor.height, scissor.width, scissor.height)
} else {
GL11.glDisable(GL11.GL_SCISSOR_TEST)
}
if (spec.loadAction == LoadAction.Clear) {
// With a scissor set, the clear is confined to the rect too - that is the point: a
// bounds-scissored composite layer never pays a full-viewport clear.
GL11.glClearColor(spec.clearRed, spec.clearGreen, spec.clearBlue, spec.clearAlpha)
GL11.glClear(GL11.GL_COLOR_BUFFER_BIT)
}
// Load preserves the target's contents (a bound FBO already holds them); DontCare needs no work on
// GL - the pass overwrites every pixel, which a tile-based backend would exploit but GL cannot.
return GlRenderPassEncoder(emptyVao)
}
override fun beginDeformCapturePass(pipeline: DeformCapturePipeline, store: DeformedPositionStore): DeformCapturePassEncoder {
val glPipeline = pipeline as GlDeformCapturePipeline
GL20.glUseProgram(glPipeline.program)
GL20.glUniform1i(glPipeline.locations.deltaTex, UNIT_DELTA)
GL20.glUniform1i(glPipeline.locations.cpTex, UNIT_CP)
// Discard the rasterizer: the capture writes positions via transform feedback and draws nothing.
GL11.glEnable(GL30.GL_RASTERIZER_DISCARD)
return GlDeformCapturePassEncoder(glPipeline, store as GlDeformedPositionStore)
}
override fun barrier(store: DeformedPositionStore) {
// The declared write→read dependency on the position store. The WSL d3d12/Mesa stack does not order
// transform-feedback writes before a later texture-buffer read, and glMemoryBarrier does not cover
// feedback writes (they are coherent-pipeline writes), so the full sync is the only reliable fix.
// Called only on pose-change frames, so a static pose pays nothing.
GL11.glFinish()
}
override fun endFrame() {
// Nothing to submit on GL: the calls already ran. A command-buffer backend would commit here.
}
}
/** Records draws into one GL render pass. */
internal class GlRenderPassEncoder(private val emptyVao: Int) : RenderPassEncoder {
private var pipeline: GlRenderPipeline? = null
private val current: GlRenderPipeline get() = pipeline ?: error("setPipeline before drawing")
// Per-program state is re-established only when the program actually switches. A uniform keeps its value
// on the program object across binds, and the renderer passes the same camera / glue state for a whole
// pass, so re-sending them per draw (as the pre-device renderer's useProgramFor did NOT) is wasted work:
// a run of same-blend drawables would otherwise churn glUseProgram + blend + samplers + camera every draw.
private var cameraApplied = false
private var glueStateApplied = false
// Scratch for the corner uniform arrays, reused across draws so the per-draw marshalling never allocates.
private val cornerCellScratch = BufferUtils.createIntBuffer(org.umamo.render.glsl.MAX_CORNERS)
private val cornerWeightScratch = BufferUtils.createFloatBuffer(org.umamo.render.glsl.MAX_CORNERS)
override fun setPipeline(pipeline: RenderPipeline) {
val glPipeline = pipeline as GlRenderPipeline
if (glPipeline === this.pipeline) {
return // already bound: program, blend, and samplers are all still in effect
}
this.pipeline = glPipeline
cameraApplied = false
glueStateApplied = false
GL20.glUseProgram(glPipeline.program)
applyBlend(glPipeline.blend)
applyCull(glPipeline.cullBackFaces)
// Sampler → texture unit is constant per program; -1 for a sampler the program lacks is a no-op.
val locations = glPipeline.locations
GL20.glUniform1i(locations.atlas, UNIT_ATLAS)
GL20.glUniform1i(locations.maskTexture, UNIT_MASK)
GL20.glUniform1i(locations.deltaTex, UNIT_DELTA)
GL20.glUniform1i(locations.cpTex, UNIT_CP)
GL20.glUniform1i(locations.positionBuffer, UNIT_POSITION)
GL20.glUniform1i(locations.layerTexture, UNIT_LAYER)
GL20.glUniform1i(locations.destTexture, UNIT_DEST)
}
override fun setCamera(worldToNdc: WorldToNdc, screenTexWidth: Int, screenTexHeight: Int) {
if (cameraApplied) {
return // the current program already holds this pass's camera (constant across the pass)
}
cameraApplied = true
val locations = current.locations
GL20.glUniform4f(locations.worldToNdc, worldToNdc.scaleX, worldToNdc.scaleY, worldToNdc.offsetX, worldToNdc.offsetY)
GL20.glUniform2f(locations.screenTexSize, screenTexWidth.toFloat(), screenTexHeight.toFloat())
}
override fun drawPuppetMesh(mesh: GpuMesh, deform: DeformUniforms, fragment: FragmentUniforms, textures: DrawTextures) {
marshalDeformUniforms(current.locations, deform, textures, cornerCellScratch, cornerWeightScratch)
setFragmentUniforms(current, fragment, textures)
val glMesh = mesh as GlMesh
GL30.glBindVertexArray(glMesh.vao)
GL11.glDrawElements(GL11.GL_TRIANGLES, glMesh.indexCount, GL11.GL_UNSIGNED_INT, 0L)
}
override fun drawGlueMesh(
mesh: GpuMesh,
store: DeformedPositionStore,
baseVertexOffset: Int,
glueIntensities: FloatArray,
fragment: FragmentUniforms,
textures: DrawTextures,
) {
val locations = current.locations
// The weld intensities and the position texture buffer are constant across the pass, so bind them
// once per glue-program bind (matching the old useProgramFor), not per glue draw.
if (!glueStateApplied) {
glueStateApplied = true
GL20.glUniform1fv(locations.glueIntensity, glueIntensities)
GL13.glActiveTexture(GL13.GL_TEXTURE0 + UNIT_POSITION)
GL11.glBindTexture(GL31.GL_TEXTURE_BUFFER, (store as GlDeformedPositionStore).textureBuffer)
}
GL20.glUniform1i(locations.baseOffset, baseVertexOffset)
setFragmentUniforms(current, fragment, textures)
val glMesh = mesh as GlMesh
GL30.glBindVertexArray(glMesh.vao)
GL11.glDrawElements(GL11.GL_TRIANGLES, glMesh.indexCount, GL11.GL_UNSIGNED_INT, 0L)
}
override fun drawAtlasPage(atlas: GpuTexture, pageWidth: Float, pageHeight: Float, fragment: FragmentUniforms) {
val locations = current.locations
GL20.glUniform2f(locations.pageSize, pageWidth, pageHeight)
setFragmentUniforms(current, fragment, DrawTextures().also { it.atlas = atlas })
GL30.glBindVertexArray(emptyVao)
GL11.glDrawArrays(GL11.GL_TRIANGLE_STRIP, 0, 4)
}
override fun drawComposite(composite: CompositeUniforms, textures: DrawTextures) {
val locations = current.locations
GL20.glUniform1i(locations.colorMode, composite.colorMode)
GL20.glUniform1i(locations.alphaMode, composite.alphaMode)
GL20.glUniform1f(locations.opacity, composite.opacity)
GL20.glUniform3f(locations.multiplyColor, composite.multiplyRed, composite.multiplyGreen, composite.multiplyBlue)
GL20.glUniform3f(locations.screenColor, composite.screenRed, composite.screenGreen, composite.screenBlue)
GL20.glUniform1i(locations.useMask, if (composite.useMask) 1 else 0)
GL20.glUniform1i(locations.invertMask, if (composite.invertMask) 1 else 0)
textures.compositeLayer?.let { bindTexture2D(UNIT_LAYER, it) }
textures.destinationSnapshot?.let { bindTexture2D(UNIT_DEST, it) }
if (composite.useMask) {
textures.maskCoverage?.let { bindTexture2D(UNIT_MASK, it) }
}
GL30.glBindVertexArray(emptyVao)
GL11.glDrawArrays(GL11.GL_TRIANGLES, 0, 3)
}
override fun drawGrid(uniforms: GridUniforms) {
val locations = current.locations
val affine = uniforms.worldToNdc
GL20.glUniform4f(locations.worldToNdc, affine.scaleX, affine.scaleY, affine.offsetX, affine.offsetY)
GL20.glUniform2f(locations.viewportSize, uniforms.viewportWidth.toFloat(), uniforms.viewportHeight.toFloat())
GL20.glUniform2f(locations.majorSpacing, uniforms.majorSpacingX, uniforms.majorSpacingY)
GL20.glUniform2f(locations.gridOrigin, uniforms.originX, uniforms.originY)
GL20.glUniform1f(locations.subdivisions, uniforms.subdivisions.toFloat())
GL20.glUniform1f(locations.lineWidthPx, uniforms.lineWidthPx)
val colors = uniforms.colors
GL20.glUniform3f(locations.backgroundColor, colors.backgroundRed, colors.backgroundGreen, colors.backgroundBlue)
GL20.glUniform3f(locations.majorColor, colors.majorRed, colors.majorGreen, colors.majorBlue)
GL20.glUniform3f(locations.minorColor, colors.minorRed, colors.minorGreen, colors.minorBlue)
GL30.glBindVertexArray(emptyVao)
GL11.glDrawArrays(GL11.GL_TRIANGLES, 0, 3)
}
override fun drawAxisLine(uniforms: AxisLineUniforms) {
val locations = current.locations
GL20.glUniform1f(locations.linePositionNdc, uniforms.linePositionNdc)
GL20.glUniform1f(locations.lineVertical, if (uniforms.vertical) 1f else 0f)
GL20.glUniform3f(locations.lineColor, uniforms.red, uniforms.green, uniforms.blue)
GL30.glBindVertexArray(emptyVao)
GL11.glDrawArrays(GL11.GL_LINES, 0, 2)
}
override fun end() {
GL30.glBindVertexArray(0)
GL20.glUseProgram(0)
// Scissor is per-pass state established in beginRenderPass; dropping it here keeps the
// between-pass operations (resolve blits, read-backs) unclipped whatever pass ran last.
GL11.glDisable(GL11.GL_SCISSOR_TEST)
}
/** Sets a draw's fragment uniforms and binds its atlas / mask textures when present. */
private fun setFragmentUniforms(pipeline: GlRenderPipeline, fragment: FragmentUniforms, textures: DrawTextures) {
val locations = pipeline.locations
GL20.glUniform1i(locations.useTexture, if (fragment.useTexture) 1 else 0)
val atlas = textures.atlas
if (fragment.useTexture && atlas != null) {
bindTexture2D(UNIT_ATLAS, atlas)
// The shader filters linear art itself, past the sampler, so it is told what the sampler would do.
val glAtlas = atlas as GlTexture
GL20.glUniform1i(locations.atlasLinear, if (glAtlas.filter == TextureFilter.Linear) 1 else 0)
GL20.glUniform1i(locations.atlasTransparentBorder, if (glAtlas.wrap == TextureWrap.ClampToTransparentBorder) 1 else 0)
} else {
GL20.glUniform4f(locations.drawColor, fragment.colorRed, fragment.colorGreen, fragment.colorBlue, fragment.colorAlpha)
}
GL20.glUniform1f(locations.opacity, fragment.opacity)
GL20.glUniform3f(locations.multiplyColor, fragment.multiplyRed, fragment.multiplyGreen, fragment.multiplyBlue)
GL20.glUniform3f(locations.screenColor, fragment.screenRed, fragment.screenGreen, fragment.screenBlue)
GL20.glUniform1f(locations.highlight, fragment.highlight)
GL20.glUniform3f(locations.highlightColor, fragment.highlightRed, fragment.highlightGreen, fragment.highlightBlue)
// Sent every draw, like the rest of these - a program that does not declare them resolves -1, and
// glUniform* with -1 is a defined no-op, so the grid / composite / axis pipelines ignore it.
GL20.glUniform3f(locations.uvAffineRow0, fragment.uvAffine[0], fragment.uvAffine[1], fragment.uvAffine[2])
GL20.glUniform3f(locations.uvAffineRow1, fragment.uvAffine[3], fragment.uvAffine[4], fragment.uvAffine[5])
GL20.glUniform1i(locations.useMask, if (fragment.useMask) 1 else 0)
GL20.glUniform1i(locations.invertMask, if (fragment.invertMask) 1 else 0)
if (fragment.useMask) {
textures.maskCoverage?.let { bindTexture2D(UNIT_MASK, it) }
}
}
}
/** Records the pass-1 deform capture into the shared position store. */
internal class GlDeformCapturePassEncoder(
private val pipeline: GlDeformCapturePipeline,
private val store: GlDeformedPositionStore,
) : DeformCapturePassEncoder {
private val cornerCellScratch = BufferUtils.createIntBuffer(org.umamo.render.glsl.MAX_CORNERS)
private val cornerWeightScratch = BufferUtils.createFloatBuffer(org.umamo.render.glsl.MAX_CORNERS)
override fun captureDeformedPositions(
mesh: GpuMesh,
deform: DeformUniforms,
textures: DrawTextures,
destinationVertexOffset: Int,
vertexCount: Int,
) {
marshalDeformUniforms(pipeline.locations, deform, textures, cornerCellScratch, cornerWeightScratch)
GL30.glBindVertexArray((mesh as GlMesh).vao)
GL30.glBindBufferRange(
GL30.GL_TRANSFORM_FEEDBACK_BUFFER,
0,
store.buffer,
destinationVertexOffset.toLong() * 2 * Float.SIZE_BYTES,
vertexCount.toLong() * 2 * Float.SIZE_BYTES,
)
GL30.glBeginTransformFeedback(GL11.GL_POINTS)
GL11.glDrawArrays(GL11.GL_POINTS, 0, vertexCount)
GL30.glEndTransformFeedback()
}
override fun end() {
GL11.glDisable(GL30.GL_RASTERIZER_DISCARD)
}
}
/**
* Marshals a mesh's per-pose deform uniforms and binds its delta (and, for a warp parent, control-point)
* texture.
*
* Shared by the pass-2 draw and the pass-1 capture so the two paths cannot diverge: they feed the exact
* same deform inputs to the exact same DEFORM_GLSL, which is what lets GpuDeformValidationTest's pin on the
* draw path also stand for the capture path. Both pass their own reused scratch buffers.
*
* @param GlUniformLocations locations The bound program's uniform locations.
* @param DeformUniforms deform The per-pose deform inputs.
* @param DrawTextures textures The delta and (warp) control-point textures to bind.
* @param IntBuffer cornerCellScratch Reused scratch for the corner-cell uniform array.
* @param FloatBuffer cornerWeightScratch Reused scratch for the corner-weight uniform array.
*/
private fun marshalDeformUniforms(
locations: GlUniformLocations,
deform: DeformUniforms,
textures: DrawTextures,
cornerCellScratch: IntBuffer,
cornerWeightScratch: FloatBuffer,
) {
val cornerCount = minOf(org.umamo.render.glsl.MAX_CORNERS, deform.cornerCount)
cornerCellScratch.clear()
cornerWeightScratch.clear()
for (cornerIndex in 0 until cornerCount) {
cornerCellScratch.put(deform.cornerCell[cornerIndex])
cornerWeightScratch.put(deform.cornerWeight[cornerIndex])
}
cornerCellScratch.flip()
cornerWeightScratch.flip()
GL20.glUniform1i(locations.cornerCount, cornerCount)
GL20.glUniform1iv(locations.cornerCell, cornerCellScratch)
GL20.glUniform1fv(locations.cornerWeight, cornerWeightScratch)
// Blend-shape columns: skip the array uploads entirely for the zero-blend common case.
val blendCount = minOf(org.umamo.render.glsl.MAX_BLEND_CORNERS, deform.blendCount)
GL20.glUniform1i(locations.blendCount, blendCount)
if (blendCount > 0) {
GL20.glUniform1iv(locations.blendCell, deform.blendCell)
GL20.glUniform1fv(locations.blendWeight, deform.blendWeight)
}
GL20.glUniform1i(locations.parentType, deform.parentType)
if (deform.parentType == 1) {
GL20.glUniform1fv(locations.rot, deform.rotation)
} else if (deform.parentType == 2) {
GL20.glUniform1i(locations.warpCols, deform.warpColumns)
GL20.glUniform1i(locations.warpRows, deform.warpRows)
GL20.glUniform1i(locations.warpBilinear, if (deform.warpBilinear) 1 else 0)
textures.warpControlPoints?.let { bindTexture2D(UNIT_CP, it) }
}
textures.deltaTexture?.let { bindTexture2D(UNIT_DELTA, it) }
}
/** Binds [texture] to the given texture unit as a 2D texture. */
private fun bindTexture2D(unit: Int, texture: GpuTexture) {
GL13.glActiveTexture(GL13.GL_TEXTURE0 + unit)
GL11.glBindTexture(GL11.GL_TEXTURE_2D, (texture as GlTexture).handle)
}
/**
* Sets the face-culling state for a pipeline. Applied on every pipeline bind (like blend) because
* GL cull state is global - a culled drawable's pipeline must not leak culling into the next draw.
* The front face is CW: corpus rest meshes bake CLOCKWISE in the renderer's Y-negated world space
* (probed 50933:0 on EricaTamamo), so a culled drawable stays visible at rest and disappears only
* when a deformation flips it inside-out. This winding convention is inferred from corpus mesh
* data, not yet cross-checked against the official editor's own culling render.
*
* @param Boolean cullBackFaces True to cull back faces; false leaves the mesh double-sided.
*/
private fun applyCull(cullBackFaces: Boolean) {
if (cullBackFaces) {
GL11.glEnable(GL11.GL_CULL_FACE)
GL11.glFrontFace(GL11.GL_CW)
GL11.glCullFace(GL11.GL_BACK)
} else {
GL11.glDisable(GL11.GL_CULL_FACE)
}
}
/** Sets the fixed-function blend state for a pipeline's blend mode. */
private fun applyBlend(blend: org.umamo.render.device.PipelineBlend) {
when (blend) {
org.umamo.render.device.PipelineBlend.Opaque -> GL11.glDisable(GL11.GL_BLEND)
org.umamo.render.device.PipelineBlend.Normal -> {
GL11.glEnable(GL11.GL_BLEND)
GL14.glBlendFuncSeparate(GL11.GL_ONE, GL11.GL_ONE_MINUS_SRC_ALPHA, GL11.GL_ONE, GL11.GL_ONE_MINUS_SRC_ALPHA)
}
org.umamo.render.device.PipelineBlend.Additive -> {
GL11.glEnable(GL11.GL_BLEND)
GL14.glBlendFuncSeparate(GL11.GL_ONE, GL11.GL_ONE, GL11.GL_ZERO, GL11.GL_ONE)
}
org.umamo.render.device.PipelineBlend.Multiply -> {
GL11.glEnable(GL11.GL_BLEND)
GL14.glBlendFuncSeparate(GL11.GL_DST_COLOR, GL11.GL_ONE_MINUS_SRC_ALPHA, GL11.GL_ZERO, GL11.GL_ONE)
}
}
}
@@ -0,0 +1,165 @@
package org.umamo.render.gl
import org.lwjgl.opengl.GL20
import org.umamo.render.device.DeformCapturePipeline
import org.umamo.render.device.DeformedPositionStore
import org.umamo.render.device.GpuMesh
import org.umamo.render.device.GpuTexture
import org.umamo.render.device.PipelineBlend
import org.umamo.render.device.RenderPipeline
import org.umamo.render.device.RenderTarget
import org.umamo.render.device.TextureFilter
import org.umamo.render.device.TextureWrap
// The GL device's concrete handles. Each wraps the GL names its interface hides; nothing outside this
// package can reach them, which is what keeps GL out of the shared renderer.
/**
* A GL texture name, with the filter and wrap it was created with.
*
* The puppet fragment shader filters art in-shader through `texelFetch`, which bypasses the sampler, so
* the encoder reads these to tell the shader what the sampler would have done.
*/
internal class GlTexture(val handle: Int, val filter: TextureFilter, val wrap: TextureWrap) : GpuTexture
/**
* A mesh's GL residency: the VAO plus every buffer it references.
*
* The buffers are kept individually, not just the VAO, because they outlive their bindings: an edit
* re-uploads [positionVbo] / [uvVbo] in place, and freeing the mesh must free all of them. 0 where the
* mesh has none - an index-less glue anchor has no [indexEbo], a non-glue mesh no [glueVbo].
*/
internal class GlMesh(
val vao: Int,
val positionVbo: Int,
val uvVbo: Int,
val glueVbo: Int,
val indexEbo: Int,
val vertexCount: Int,
val indexCount: Int,
) : GpuMesh
/**
* A render target: its framebuffer plus whichever attachment backs it.
*
* Exactly one of [colorTexture] / [colorRenderbuffer] is non-zero, chosen by `RenderTargetSpec.sampled`.
* A renderbuffer is the cheaper write-only surface but cannot be sampled OR read back directly, which is
* precisely why the flag exists rather than always allocating a texture.
*/
internal class GlRenderTarget(
val framebuffer: Int,
val colorTexture: Int,
val colorRenderbuffer: Int,
val width: Int,
val height: Int,
) : RenderTarget {
override val sampledTexture: GpuTexture? = if (colorTexture != 0) GlTexture(colorTexture, TextureFilter.Linear, TextureWrap.ClampToEdge) else null
}
/**
* The shared pass-1 position store: a buffer plus the texture-buffer view pass 2 samples it through.
*
* A texture buffer object today, which is desktop-GL only (GLES has them at 3.2, and the Android baseline
* is 3.0). The GLES port repacks this as a 2D texture; nothing above the device sees the difference.
*/
internal class GlDeformedPositionStore(
val buffer: Int,
val textureBuffer: Int,
val vertexCapacity: Int,
) : DeformedPositionStore
/**
* Every uniform any of this backend's programs declares, resolved once at pipeline creation.
*
* One flat set rather than a per-purpose struct, because GL makes it free: `glGetUniformLocation` returns
* -1 for a uniform a program does not declare (or that its compiler optimised away), and `glUniform*`
* with -1 is a defined no-op. So the grid pipeline simply has -1 for every puppet uniform and setting
* them costs a branch in the driver.
*
* Resolving them ONCE here is the point: the renderer previously looked a location up by name on every
* draw - 36 call sites' worth of string lookups per frame.
*/
internal class GlUniformLocations(program: Int) {
// Per-pass. viewportSize is the grid program's genuine viewport extent; screenTexSize is the
// puppet/composite programs' screen-space texture divisor (the side targets' allocated size,
// which the grow-only capacity can hold above the viewport size).
val worldToNdc = GL20.glGetUniformLocation(program, "worldToNdc")
val viewportSize = GL20.glGetUniformLocation(program, "viewportSize")
val screenTexSize = GL20.glGetUniformLocation(program, "screenTexSize")
// Samplers
val atlas = GL20.glGetUniformLocation(program, "atlas")
val maskTexture = GL20.glGetUniformLocation(program, "maskTexture")
val deltaTex = GL20.glGetUniformLocation(program, "deltaTex")
val cpTex = GL20.glGetUniformLocation(program, "cpTex")
val positionBuffer = GL20.glGetUniformLocation(program, "positionBuffer")
// Deform
val cornerCount = GL20.glGetUniformLocation(program, "cornerCount")
val cornerCell = GL20.glGetUniformLocation(program, "cornerCell")
val cornerWeight = GL20.glGetUniformLocation(program, "cornerWeight")
val blendCount = GL20.glGetUniformLocation(program, "blendCount")
val blendCell = GL20.glGetUniformLocation(program, "blendCell")
val blendWeight = GL20.glGetUniformLocation(program, "blendWeight")
val parentType = GL20.glGetUniformLocation(program, "parentType")
val rot = GL20.glGetUniformLocation(program, "rot")
val warpCols = GL20.glGetUniformLocation(program, "warpCols")
val warpRows = GL20.glGetUniformLocation(program, "warpRows")
val warpBilinear = GL20.glGetUniformLocation(program, "warpBilinear")
// Glue
val baseOffset = GL20.glGetUniformLocation(program, "baseOffset")
val glueIntensity = GL20.glGetUniformLocation(program, "glueIntensity")
// Fragment
val useTexture = GL20.glGetUniformLocation(program, "useTexture")
val drawColor = GL20.glGetUniformLocation(program, "drawColor")
val opacity = GL20.glGetUniformLocation(program, "opacity")
val useMask = GL20.glGetUniformLocation(program, "useMask")
val invertMask = GL20.glGetUniformLocation(program, "invertMask")
val highlight = GL20.glGetUniformLocation(program, "highlight")
val highlightColor = GL20.glGetUniformLocation(program, "highlightColor")
val uvAffineRow0 = GL20.glGetUniformLocation(program, "uvAffineRow0")
val uvAffineRow1 = GL20.glGetUniformLocation(program, "uvAffineRow1")
val atlasLinear = GL20.glGetUniformLocation(program, "atlasLinear")
val atlasTransparentBorder = GL20.glGetUniformLocation(program, "atlasTransparentBorder")
// Atlas page
val pageSize = GL20.glGetUniformLocation(program, "pageSize")
// Layer composite
val layerTexture = GL20.glGetUniformLocation(program, "layerTexture")
val destTexture = GL20.glGetUniformLocation(program, "destTexture")
val colorMode = GL20.glGetUniformLocation(program, "colorMode")
val alphaMode = GL20.glGetUniformLocation(program, "alphaMode")
val multiplyColor = GL20.glGetUniformLocation(program, "multiplyColor")
val screenColor = GL20.glGetUniformLocation(program, "screenColor")
// Grid backdrop
val majorSpacing = GL20.glGetUniformLocation(program, "majorSpacing")
val subdivisions = GL20.glGetUniformLocation(program, "subdivisions")
val lineWidthPx = GL20.glGetUniformLocation(program, "lineWidthPx")
val backgroundColor = GL20.glGetUniformLocation(program, "backgroundColor")
val majorColor = GL20.glGetUniformLocation(program, "majorColor")
val minorColor = GL20.glGetUniformLocation(program, "minorColor")
val gridOrigin = GL20.glGetUniformLocation(program, "gridOrigin")
// Axis line
val linePositionNdc = GL20.glGetUniformLocation(program, "linePositionNdc")
val lineVertical = GL20.glGetUniformLocation(program, "lineVertical")
val lineColor = GL20.glGetUniformLocation(program, "lineColor")
}
/** A linked draw program with its blend, cull state, and resolved uniform locations. */
internal class GlRenderPipeline(
val program: Int,
val blend: PipelineBlend,
val cullBackFaces: Boolean,
val locations: GlUniformLocations,
) : RenderPipeline
/** The transform-feedback program that captures deformed positions without rasterizing. */
internal class GlDeformCapturePipeline(
val program: Int,
val locations: GlUniformLocations,
) : DeformCapturePipeline
@@ -0,0 +1,596 @@
package org.umamo.render.gl
import org.lwjgl.BufferUtils
import org.lwjgl.opengl.GL11
import org.lwjgl.opengl.GL12
import org.lwjgl.opengl.GL13
import org.lwjgl.opengl.GL15
import org.lwjgl.opengl.GL20
import org.lwjgl.opengl.GL21
import org.lwjgl.opengl.GL30
import org.lwjgl.opengl.GL31
import org.lwjgl.opengl.GL32
import org.umamo.format.raster.RasterImage
import org.umamo.render.device.DeformCapturePipeline
import org.umamo.render.device.DeformedPositionStore
import org.umamo.render.device.FrameEncoder
import org.umamo.render.device.GpuMesh
import org.umamo.render.device.GpuTexture
import org.umamo.render.device.MeshSpec
import org.umamo.render.device.PipelinePurpose
import org.umamo.render.device.ReadbackTicket
import org.umamo.render.device.RenderDevice
import org.umamo.render.device.RenderPipeline
import org.umamo.render.device.RenderPipelineSpec
import org.umamo.render.device.RenderTarget
import org.umamo.render.device.RenderTargetSpec
import org.umamo.render.device.ScissorRect
import org.umamo.render.device.TextureFilter
import org.umamo.render.device.TextureFormat
import org.umamo.render.device.TextureWrap
import org.umamo.render.glsl.GlslDialect
import org.umamo.render.glsl.atlasPageVertexShader
import org.umamo.render.glsl.axisFragmentShader
import org.umamo.render.glsl.axisVertexShader
import org.umamo.render.glsl.compositeFragmentShader
import org.umamo.render.glsl.compositeVertexShader
import org.umamo.render.glsl.glueVertexShader
import org.umamo.render.glsl.gridFragmentShader
import org.umamo.render.glsl.gridVertexShader
import org.umamo.render.glsl.puppetFragmentShader
import org.umamo.render.glsl.puppetVertexShader
import org.umamo.render.glsl.tfDeformVertexShader
import org.umamo.render.glsl.tfDiscardFragmentShader
import org.umamo.render.puppet.flipRowsVertically
import java.nio.ByteBuffer
/**
* The desktop OpenGL 3.3 core [RenderDevice], over LWJGL.
*
* This is where the GL lives. Everything above it - the puppet renderer, the eval, the pose resolution -
* is backend-neutral, so a second backend is a second device rather than a second renderer. Every method
* assumes a GL context is current on the calling thread; the host makes it so.
*
* A near-transliteration of this becomes the Android GLES 3.0 device: the calls are the same, differing
* only in binding style (LWJGL statics vs the GLES out-param form) and the one place GLES 3.0 lacks a
* texture buffer (the glue store, [createDeformedPositionStore], where the GLES port repacks as a 2D
* texture behind [DeformedPositionStore]).
*/
class GlRenderDevice : RenderDevice {
// An empty VAO for the attribute-less draws (grid, axis lines, atlas page): a core profile still
// requires a bound VAO even when the vertex shader synthesises its positions from gl_VertexID.
private var emptyVao = 0
// Pipelines are immutable and reused every frame, so they are cached by their spec rather than rebuilt.
private val renderPipelines = HashMap<RenderPipelineSpec, GlRenderPipeline>()
private var deformCapturePipeline: GlDeformCapturePipeline? = null
private fun ensureEmptyVao(): Int {
if (emptyVao == 0) {
emptyVao = GL30.glGenVertexArrays()
}
return emptyVao
}
override fun createTexture(
width: Int,
height: Int,
format: TextureFormat,
filter: TextureFilter,
pixels: ByteArray?,
wrap: TextureWrap,
): GpuTexture {
val handle = GL11.glGenTextures()
GL11.glBindTexture(GL11.GL_TEXTURE_2D, handle)
setTextureParameters(filter, wrap)
val pixelBuffer =
pixels?.let {
BufferUtils.createByteBuffer(it.size).apply {
put(it)
flip()
}
}
GL11.glTexImage2D(
GL11.GL_TEXTURE_2D,
0,
internalFormatOf(format),
width,
height,
0,
pixelFormatOf(format),
pixelTypeOf(format),
pixelBuffer,
)
return GlTexture(handle, filter, wrap)
}
override fun createFloatTexture(width: Int, height: Int, filter: TextureFilter, texels: FloatArray): GpuTexture {
val handle = GL11.glGenTextures()
GL11.glBindTexture(GL11.GL_TEXTURE_2D, handle)
setTextureParameters(filter, TextureWrap.ClampToEdge)
val texelBuffer =
BufferUtils.createFloatBuffer(texels.size).apply {
put(texels)
flip()
}
GL11.glTexImage2D(GL11.GL_TEXTURE_2D, 0, GL30.GL_RG32F, width, height, 0, GL30.GL_RG, GL11.GL_FLOAT, texelBuffer)
return GlTexture(handle, filter, TextureWrap.ClampToEdge)
}
override fun updateFloatTexture(texture: GpuTexture, width: Int, height: Int, texels: FloatArray) {
val glTexture = texture as GlTexture
val texelBuffer =
BufferUtils.createFloatBuffer(texels.size).apply {
put(texels)
flip()
}
GL11.glBindTexture(GL11.GL_TEXTURE_2D, glTexture.handle)
GL11.glTexImage2D(GL11.GL_TEXTURE_2D, 0, GL30.GL_RG32F, width, height, 0, GL30.GL_RG, GL11.GL_FLOAT, texelBuffer)
}
override fun createMesh(spec: MeshSpec): GpuMesh {
val vao = GL30.glGenVertexArrays()
GL30.glBindVertexArray(vao)
val positionVbo = uploadArrayBuffer(spec.restPositions, GL15.GL_DYNAMIC_DRAW)
GL20.glEnableVertexAttribArray(0)
GL20.glVertexAttribPointer(0, 2, GL11.GL_FLOAT, false, 2 * Float.SIZE_BYTES, 0L)
val vertexCount = spec.restPositions.size / 2
// A mesh whose UVs are shorter than its vertices gets a zero-filled UV buffer of the right length,
// so an in-place UV re-upload later has a target of the expected size.
val safeUvs = if (spec.uvs.size >= vertexCount * 2) spec.uvs else FloatArray(vertexCount * 2)
val uvVbo = uploadArrayBuffer(safeUvs, GL15.GL_DYNAMIC_DRAW)
GL20.glEnableVertexAttribArray(1)
GL20.glVertexAttribPointer(1, 2, GL11.GL_FLOAT, false, 2 * Float.SIZE_BYTES, 0L)
var glueVbo = 0
spec.glueAttributes?.let { attributes ->
glueVbo = GL15.glGenBuffers()
GL15.glBindBuffer(GL15.GL_ARRAY_BUFFER, glueVbo)
GL15.glBufferData(GL15.GL_ARRAY_BUFFER, interleaveGlueAttributes(attributes), GL15.GL_STATIC_DRAW)
val stride = 3 * Int.SIZE_BYTES
GL20.glEnableVertexAttribArray(2)
GL30.glVertexAttribIPointer(2, 1, GL11.GL_INT, stride, 0L)
GL20.glEnableVertexAttribArray(3)
GL30.glVertexAttribIPointer(3, 1, GL11.GL_INT, stride, Int.SIZE_BYTES.toLong())
GL20.glEnableVertexAttribArray(4)
GL20.glVertexAttribPointer(4, 1, GL11.GL_FLOAT, false, stride, (2 * Int.SIZE_BYTES).toLong())
}
var indexEbo = 0
if (spec.indices.isNotEmpty()) {
val indexBuffer =
BufferUtils.createIntBuffer(spec.indices.size).apply {
put(spec.indices)
flip()
}
indexEbo = GL15.glGenBuffers()
GL15.glBindBuffer(GL15.GL_ELEMENT_ARRAY_BUFFER, indexEbo)
GL15.glBufferData(GL15.GL_ELEMENT_ARRAY_BUFFER, indexBuffer, GL15.GL_STATIC_DRAW)
}
GL30.glBindVertexArray(0)
return GlMesh(vao, positionVbo, uvVbo, glueVbo, indexEbo, vertexCount, spec.indices.size)
}
override fun updateMeshPositions(mesh: GpuMesh, restPositions: FloatArray) {
subDataArrayBuffer((mesh as GlMesh).positionVbo, restPositions)
}
override fun updateMeshUvs(mesh: GpuMesh, uvs: FloatArray) {
subDataArrayBuffer((mesh as GlMesh).uvVbo, uvs)
}
override fun createRenderTarget(spec: RenderTargetSpec): RenderTarget {
val framebuffer = GL30.glGenFramebuffers()
GL30.glBindFramebuffer(GL30.GL_FRAMEBUFFER, framebuffer)
var colorTexture = 0
var colorRenderbuffer = 0
if (spec.sampled) {
colorTexture = GL11.glGenTextures()
GL11.glBindTexture(GL11.GL_TEXTURE_2D, colorTexture)
setTextureParameters(TextureFilter.Linear, TextureWrap.ClampToEdge)
GL11.glTexImage2D(
GL11.GL_TEXTURE_2D,
0,
internalFormatOf(spec.format),
spec.width,
spec.height,
0,
pixelFormatOf(spec.format),
pixelTypeOf(spec.format),
null as ByteBuffer?,
)
GL30.glFramebufferTexture2D(GL30.GL_FRAMEBUFFER, GL30.GL_COLOR_ATTACHMENT0, GL11.GL_TEXTURE_2D, colorTexture, 0)
} else {
// A write-only surface: cheaper, but cannot be sampled or read back directly.
colorRenderbuffer = GL30.glGenRenderbuffers()
GL30.glBindRenderbuffer(GL30.GL_RENDERBUFFER, colorRenderbuffer)
GL30.glRenderbufferStorage(GL30.GL_RENDERBUFFER, internalFormatOf(spec.format), spec.width, spec.height)
GL30.glFramebufferRenderbuffer(GL30.GL_FRAMEBUFFER, GL30.GL_COLOR_ATTACHMENT0, GL30.GL_RENDERBUFFER, colorRenderbuffer)
}
return GlRenderTarget(framebuffer, colorTexture, colorRenderbuffer, spec.width, spec.height)
}
override fun createDeformedPositionStore(vertexCapacity: Int): DeformedPositionStore {
val buffer = GL15.glGenBuffers()
GL15.glBindBuffer(GL31.GL_TEXTURE_BUFFER, buffer)
GL15.glBufferData(GL31.GL_TEXTURE_BUFFER, vertexCapacity.toLong() * 2 * Float.SIZE_BYTES, GL15.GL_DYNAMIC_COPY)
val textureBuffer = GL11.glGenTextures()
GL11.glBindTexture(GL31.GL_TEXTURE_BUFFER, textureBuffer)
GL31.glTexBuffer(GL31.GL_TEXTURE_BUFFER, GL30.GL_RG32F, buffer)
return GlDeformedPositionStore(buffer, textureBuffer, vertexCapacity)
}
override fun createRenderPipeline(spec: RenderPipelineSpec): RenderPipeline =
renderPipelines.getOrPut(spec) {
val (vertexSource, fragmentSource) = sourcesFor(spec.purpose)
val program = linkGlProgram(vertexSource, fragmentSource, spec.purpose.name)
GlRenderPipeline(program, spec.blend, spec.cullBackFaces, GlUniformLocations(program))
}
override fun createDeformCapturePipeline(): DeformCapturePipeline =
deformCapturePipeline ?: run {
val program = attachGlShaders(tfDeformVertexShader(DIALECT), tfDiscardFragmentShader(DIALECT))
GL30.glTransformFeedbackVaryings(program, arrayOf("outWorld"), GL30.GL_INTERLEAVED_ATTRIBS)
GL20.glLinkProgram(program)
check(GL20.glGetProgrami(program, GL20.GL_LINK_STATUS) != GL11.GL_FALSE) {
"deform-capture program link failed: ${GL20.glGetProgramInfoLog(program)}"
}
GlDeformCapturePipeline(program, GlUniformLocations(program)).also { deformCapturePipeline = it }
}
override fun destroyTexture(texture: GpuTexture) {
GL11.glDeleteTextures((texture as GlTexture).handle)
}
override fun destroyMesh(mesh: GpuMesh) {
val glMesh = mesh as GlMesh
GL30.glDeleteVertexArrays(glMesh.vao)
GL15.glDeleteBuffers(glMesh.positionVbo)
GL15.glDeleteBuffers(glMesh.uvVbo)
if (glMesh.glueVbo != 0) {
GL15.glDeleteBuffers(glMesh.glueVbo)
}
if (glMesh.indexEbo != 0) {
GL15.glDeleteBuffers(glMesh.indexEbo)
}
}
override fun destroyRenderTarget(target: RenderTarget) {
val glTarget = target as GlRenderTarget
GL30.glDeleteFramebuffers(glTarget.framebuffer)
if (glTarget.colorTexture != 0) {
GL11.glDeleteTextures(glTarget.colorTexture)
}
if (glTarget.colorRenderbuffer != 0) {
GL30.glDeleteRenderbuffers(glTarget.colorRenderbuffer)
}
}
override fun beginFrame(): FrameEncoder = GlFrameEncoder(ensureEmptyVao())
override fun resolve(source: RenderTarget, destination: RenderTarget, region: ScissorRect?) {
val glSource = source as GlRenderTarget
val glDestination = destination as GlRenderTarget
resolveUsed(glSource, glSource.width, glSource.height, glDestination, glDestination.width, glDestination.height, region)
}
override fun resolveUsed(
source: RenderTarget,
sourceUsedWidth: Int,
sourceUsedHeight: Int,
destination: RenderTarget,
destinationUsedWidth: Int,
destinationUsedHeight: Int,
region: ScissorRect?,
) {
val glSource = source as GlRenderTarget
val glDestination = destination as GlRenderTarget
GL30.glBindFramebuffer(GL30.GL_READ_FRAMEBUFFER, glSource.framebuffer)
GL30.glBindFramebuffer(GL30.GL_DRAW_FRAMEBUFFER, glDestination.framebuffer)
// Content sits at GL (0, 0): every pass runs glViewport(0, 0, used, used), so the used region
// IS the bottom-left rows. GL_LINEAR makes the downscale a box filter - the supersample
// resolve. On GL this whole primitive IS a blit; on Metal it cannot be (a blit encoder neither
// filters nor scales), which is why the interface names the effect rather than the mechanism.
if (region == null) {
GL30.glBlitFramebuffer(
0,
0,
sourceUsedWidth,
sourceUsedHeight,
0,
0,
destinationUsedWidth,
destinationUsedHeight,
GL11.GL_COLOR_BUFFER_BIT,
GL11.GL_LINEAR,
)
} else {
// A same-size sub-rectangle copy (the composite path's snapshot). The rect is
// top-left-origin per the ScissorRect contract; GL blits bottom-up, so the flip is against
// the USED height - flipping against a larger allocation would land above the content.
val bottomUpY = sourceUsedHeight - region.y - region.height
GL30.glBlitFramebuffer(
region.x,
bottomUpY,
region.x + region.width,
bottomUpY + region.height,
region.x,
bottomUpY,
region.x + region.width,
bottomUpY + region.height,
GL11.GL_COLOR_BUFFER_BIT,
GL11.GL_NEAREST,
)
}
GL30.glBindFramebuffer(GL30.GL_FRAMEBUFFER, glDestination.framebuffer)
}
/** A recyclable pixel-buffer object and its current byte capacity. */
private class Pbo(val id: Int, var capacity: Int)
/**
* An in-flight asynchronous read-back: the staging PBO, the fence gating it, and the read's extent.
* [spent] flips when the ticket is consumed or cancelled, making both one-shot and idempotent.
*/
private class GlReadbackTicket(
val pbo: Pbo,
val fence: Long,
val width: Int,
val height: Int,
var spent: Boolean = false,
) : ReadbackTicket
// Staging PBOs are recycled rather than freed: a viewport read-back runs per frame, and reallocating
// a multi-megabyte buffer 60x/sec is churn the pool exists to avoid. Render-thread only.
private val freePbos = ArrayDeque<Pbo>()
override fun beginReadback(target: RenderTarget): ReadbackTicket {
val glTarget = target as GlRenderTarget
return beginReadback(glTarget, glTarget.width, glTarget.height)
}
override fun beginReadback(target: RenderTarget, usedWidth: Int, usedHeight: Int): ReadbackTicket {
val glTarget = target as GlRenderTarget
GL30.glBindFramebuffer(GL30.GL_READ_FRAMEBUFFER, glTarget.framebuffer)
val pbo = acquirePbo(usedWidth * usedHeight * 4)
GL15.glBindBuffer(GL21.GL_PIXEL_PACK_BUFFER, pbo.id)
// With a PBO bound, the last argument is a BUFFER OFFSET, not a client pointer - glReadPixels
// returns immediately and the copy happens asynchronously on the GPU timeline. The used
// region is the bottom-left rows (passes viewport at the origin), so the read starts at (0, 0).
GL11.glReadPixels(0, 0, usedWidth, usedHeight, GL11.GL_RGBA, GL11.GL_UNSIGNED_BYTE, 0L)
GL15.glBindBuffer(GL21.GL_PIXEL_PACK_BUFFER, 0)
val fence = GL32.glFenceSync(GL32.GL_SYNC_GPU_COMMANDS_COMPLETE, 0)
GL11.glFlush() // submit the commands + fence so the fence can eventually signal
return GlReadbackTicket(pbo, fence, usedWidth, usedHeight)
}
override fun pollReadback(ticket: ReadbackTicket): RasterImage? {
val glTicket = ticket as GlReadbackTicket
check(!glTicket.spent) { "pollReadback on a spent ticket" }
val status = GL32.glClientWaitSync(glTicket.fence, 0, 0L)
if (status != GL32.GL_ALREADY_SIGNALED && status != GL32.GL_CONDITION_SATISFIED) {
return null // still in flight; the ticket stays live to poll again
}
// The fence signaled, so the read is done and the ticket is consumed HERE - exactly once, whether or
// not the map below succeeds. Returning null past this point would make the caller treat a consumed
// ticket as still-in-flight and re-poll it, tripping the spent check and killing the render thread.
glTicket.spent = true
GL15.glBindBuffer(GL21.GL_PIXEL_PACK_BUFFER, glTicket.pbo.id)
// Explicitly typed: the inferred type would carry LWJGL's jspecify @Nullable, which is not
// on this module's classpath and fails compilation.
val mapped: ByteBuffer? = GL15.glMapBuffer(GL21.GL_PIXEL_PACK_BUFFER, GL15.GL_READ_ONLY)
val rowBytes = glTicket.width * 4
val topDown = ByteArray(rowBytes * glTicket.height)
if (mapped != null) {
// Flip the GL bottom-up rows straight out of the mapped PBO into the API's top-first contract -
// one bulk get per row, the direct-buffer equivalent of System.arraycopy.
for (row in 0 until glTicket.height) {
mapped.position((glTicket.height - 1 - row) * rowBytes)
mapped.get(topDown, row * rowBytes, rowBytes)
}
GL15.glUnmapBuffer(GL21.GL_PIXEL_PACK_BUFFER) // only when the map actually succeeded
}
// A map failure (a driver error that should never happen) leaves topDown zero-filled: one black
// frame rather than a permanently frozen viewport, and null keeps meaning "still in flight".
GL15.glBindBuffer(GL21.GL_PIXEL_PACK_BUFFER, 0)
GL32.glDeleteSync(glTicket.fence)
freePbos.addLast(glTicket.pbo)
return RasterImage(glTicket.width, glTicket.height, topDown)
}
override fun cancelReadback(ticket: ReadbackTicket) {
val glTicket = ticket as GlReadbackTicket
if (glTicket.spent) {
return
}
glTicket.spent = true
GL32.glDeleteSync(glTicket.fence)
freePbos.addLast(glTicket.pbo)
}
/**
* Acquires a PBO with at least [capacity] bytes from the free pool (allocating/growing as needed).
* GL_STREAM_READ: written by GL, read once by the client.
*
* @param Int capacity The minimum byte capacity needed.
* @return Pbo The acquired PBO.
*/
private fun acquirePbo(capacity: Int): Pbo {
val pbo = freePbos.removeFirstOrNull() ?: Pbo(GL15.glGenBuffers(), 0)
if (pbo.capacity < capacity) {
GL15.glBindBuffer(GL21.GL_PIXEL_PACK_BUFFER, pbo.id)
GL15.glBufferData(GL21.GL_PIXEL_PACK_BUFFER, capacity.toLong(), GL15.GL_STREAM_READ)
GL15.glBindBuffer(GL21.GL_PIXEL_PACK_BUFFER, 0)
pbo.capacity = capacity
}
return pbo
}
override fun readPixels(target: RenderTarget): RasterImage {
val glTarget = target as GlRenderTarget
return readPixels(glTarget, glTarget.width, glTarget.height)
}
override fun readPixels(target: RenderTarget, usedWidth: Int, usedHeight: Int): RasterImage {
val glTarget = target as GlRenderTarget
GL30.glBindFramebuffer(GL30.GL_READ_FRAMEBUFFER, glTarget.framebuffer)
val pixels = BufferUtils.createByteBuffer(usedWidth * usedHeight * 4)
// The used region is the bottom-left rows (passes viewport at the origin): read from (0, 0).
GL11.glReadPixels(0, 0, usedWidth, usedHeight, GL11.GL_RGBA, GL11.GL_UNSIGNED_BYTE, pixels)
val bottomUp = ByteArray(usedWidth * usedHeight * 4)
pixels.get(bottomUp)
// GL reads bottom-up; RasterImage is top-first. The flip is this backend's; no caller asks.
return RasterImage(usedWidth, usedHeight, flipRowsVertically(bottomUp, usedWidth, usedHeight))
}
override fun maxRenderTargetSize(): Int {
val viewportDimensions = IntArray(2)
GL11.glGetIntegerv(GL11.GL_MAX_VIEWPORT_DIMS, viewportDimensions)
val textureSize = GL11.glGetInteger(GL11.GL_MAX_TEXTURE_SIZE)
val renderbufferSize = GL11.glGetInteger(GL30.GL_MAX_RENDERBUFFER_SIZE)
return minOf(textureSize, renderbufferSize, viewportDimensions[0], viewportDimensions[1])
}
override fun describeBackend(): String {
val renderer = GL11.glGetString(GL11.GL_RENDERER)
val version = GL11.glGetString(GL11.GL_VERSION)
val vendor = GL11.glGetString(GL11.GL_VENDOR)
val glsl = GL11.glGetString(GL20.GL_SHADING_LANGUAGE_VERSION)
return "renderer=$renderer | version=$version | vendor=$vendor | glsl=$glsl"
}
/** The (vertex, fragment) GLSL for a pipeline purpose - this backend's shader library, keyed by purpose. */
private fun sourcesFor(purpose: PipelinePurpose): Pair<String, String> =
when (purpose) {
PipelinePurpose.PuppetDeformDraw -> puppetVertexShader(DIALECT) to puppetFragmentShader(DIALECT)
PipelinePurpose.PuppetGlueDraw -> glueVertexShader(DIALECT) to puppetFragmentShader(DIALECT)
PipelinePurpose.AtlasPageDraw -> atlasPageVertexShader(DIALECT) to puppetFragmentShader(DIALECT)
PipelinePurpose.GridBackdrop -> gridVertexShader(DIALECT) to gridFragmentShader(DIALECT)
PipelinePurpose.WorldAxisLine -> axisVertexShader(DIALECT) to axisFragmentShader(DIALECT)
PipelinePurpose.Composite -> compositeVertexShader(DIALECT) to compositeFragmentShader(DIALECT)
}
/**
* Sets nearest/linear filtering and the requested wrapping on the currently-bound 2D texture.
*
* The border color is set only for the border mode: it is per-texture state, so leaving it alone on the
* edge-clamp path costs one call less and changes nothing that path can observe.
*
* @param TextureFilter filter The filtering mode.
* @param TextureWrap wrap The wrapping mode, applied to both axes.
*/
private fun setTextureParameters(filter: TextureFilter, wrap: TextureWrap) {
val glFilter = if (filter == TextureFilter.Nearest) GL11.GL_NEAREST else GL11.GL_LINEAR
GL11.glTexParameteri(GL11.GL_TEXTURE_2D, GL11.GL_TEXTURE_MIN_FILTER, glFilter)
GL11.glTexParameteri(GL11.GL_TEXTURE_2D, GL11.GL_TEXTURE_MAG_FILTER, glFilter)
val glWrap = if (wrap == TextureWrap.ClampToTransparentBorder) GL13.GL_CLAMP_TO_BORDER else GL12.GL_CLAMP_TO_EDGE
GL11.glTexParameteri(GL11.GL_TEXTURE_2D, GL11.GL_TEXTURE_WRAP_S, glWrap)
GL11.glTexParameteri(GL11.GL_TEXTURE_2D, GL11.GL_TEXTURE_WRAP_T, glWrap)
if (wrap == TextureWrap.ClampToTransparentBorder) {
// Transparent AND black: under linear filtering the border's RGB joins the blend across the
// art's outermost half-texel, so a border that is merely alpha-zero but colored tints that
// fringe. Zero everywhere matches what the packed atlas's own padding contributes there.
GL11.glTexParameterfv(GL11.GL_TEXTURE_2D, GL11.GL_TEXTURE_BORDER_COLOR, floatArrayOf(0f, 0f, 0f, 0f))
}
}
private fun internalFormatOf(format: TextureFormat): Int = if (format == TextureFormat.Rgba8) GL11.GL_RGBA8 else GL30.GL_RG32F
private fun pixelFormatOf(format: TextureFormat): Int = if (format == TextureFormat.Rgba8) GL11.GL_RGBA else GL30.GL_RG
private fun pixelTypeOf(format: TextureFormat): Int = if (format == TextureFormat.Rgba8) GL11.GL_UNSIGNED_BYTE else GL11.GL_FLOAT
/** Uploads a float array into a fresh GL_ARRAY_BUFFER with the given usage; leaves it bound. */
private fun uploadArrayBuffer(values: FloatArray, usage: Int): Int {
val buffer =
BufferUtils.createFloatBuffer(values.size).apply {
put(values)
flip()
}
val vbo = GL15.glGenBuffers()
GL15.glBindBuffer(GL15.GL_ARRAY_BUFFER, vbo)
GL15.glBufferData(GL15.GL_ARRAY_BUFFER, buffer, usage)
return vbo
}
// Reusable scratch for in-place VBO re-uploads, grown on demand so a live preview edit never allocates.
private var uploadScratch = BufferUtils.createFloatBuffer(0)
/** Re-specifies a whole array buffer's contents in place, reusing the scratch buffer. */
private fun subDataArrayBuffer(vbo: Int, values: FloatArray) {
if (uploadScratch.capacity() < values.size) {
uploadScratch = BufferUtils.createFloatBuffer(values.size)
}
uploadScratch.clear()
uploadScratch.put(values).flip()
GL15.glBindBuffer(GL15.GL_ARRAY_BUFFER, vbo)
GL15.glBufferSubData(GL15.GL_ARRAY_BUFFER, 0L, uploadScratch)
}
}
/** This backend is desktop OpenGL 3.3 core; the shared GLSL is emitted for it. */
private val DIALECT = GlslDialect.Core330
/**
* Interleaves a mesh's planned weld attributes into the 12-byte-per-vertex form the glue VAO reads:
* int partner global index, int glue index, float weld weight, in the native byte order [BufferUtils]
* allocates - which is what `glVertexAttribIPointer` reads back.
*
* The layout is GL's; `org.umamo.render.puppet.planGlueLayout` decided the values. A free function, not
* a device method, since it touches no device state.
*
* @param GlueVertexAttributes attributes The mesh's planned per-vertex weld attributes.
* @return ByteBuffer The interleaved buffer, flipped and ready to upload.
*/
private fun interleaveGlueAttributes(attributes: org.umamo.render.puppet.GlueVertexAttributes): ByteBuffer {
val vertexCount = attributes.partnerIndex.size
val buffer = BufferUtils.createByteBuffer(vertexCount * 3 * Int.SIZE_BYTES)
for (vertexIndex in 0 until vertexCount) {
buffer.putInt(attributes.partnerIndex[vertexIndex])
buffer.putInt(attributes.glueIndex[vertexIndex])
buffer.putFloat(attributes.weldWeight[vertexIndex])
}
buffer.flip()
return buffer
}
/**
* Links a GL program from vertex + fragment source, throwing with the info log on failure.
*
* @param String vertexSource The vertex-stage GLSL.
* @param String fragmentSource The fragment-stage GLSL.
* @param String label A name for the failure message.
* @return Int The linked program handle.
*/
internal fun linkGlProgram(vertexSource: String, fragmentSource: String, label: String): Int {
val program = attachGlShaders(vertexSource, fragmentSource)
GL20.glLinkProgram(program)
check(GL20.glGetProgrami(program, GL20.GL_LINK_STATUS) != GL11.GL_FALSE) {
"$label program link failed: ${GL20.glGetProgramInfoLog(program)}"
}
return program
}
/** Compiles and attaches both stages onto a fresh program (not yet linked, so the TF varyings can be set). */
internal fun attachGlShaders(vertexSource: String, fragmentSource: String): Int {
val vertexShader = compileGlShader(GL20.GL_VERTEX_SHADER, vertexSource)
val fragmentShader = compileGlShader(GL20.GL_FRAGMENT_SHADER, fragmentSource)
val program = GL20.glCreateProgram()
GL20.glAttachShader(program, vertexShader)
GL20.glAttachShader(program, fragmentShader)
return program
}
/** Compiles one shader stage, throwing with the info log if compilation fails. */
internal fun compileGlShader(stage: Int, source: String): Int {
val shader = GL20.glCreateShader(stage)
GL20.glShaderSource(shader, source)
GL20.glCompileShader(shader)
check(GL20.glGetShaderi(shader, GL20.GL_COMPILE_STATUS) != GL11.GL_FALSE) {
"GL shader compile failed: ${GL20.glGetShaderInfoLog(shader)}"
}
return shader
}
@@ -0,0 +1,194 @@
package org.umamo.render
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.moc3.Moc3
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.interop.moc3.import.Moc3Import
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.Deformer
import java.io.File
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* Cross-import blend-binding parity: the same corpus model imported from `.cmo3` (editor forms)
* and from its baked `.moc3` (delta rows + the grid-at-default reference re-added) must produce
* structurally IDENTICAL BlendShapeBindings - same objects, driving parameters, keys, neutral
* placement, and limit curves.
*
* Form VALUES are compared under per-kind ceilings rather than exactly - float noise accumulates
* through the delta + grid-at-default reconstruction and the canvas-space rewrite. Measured, the
* corpus reconstructs SUB-PIXEL (mesh <= 0.36 px, control points and rotation fields <= 3e-4), so
* the pinned ceilings sit just above that class and reject any space or reference-frame
* regression outright. End-to-end geometric parity against the Umamo C++ Runtime is
* BlendShapeOracleTest's job; this test isolates the import mapping itself.
*
* Gated on `cmo3.probe` + `moc3.samples` (the build defaults both); skips when absent.
*/
class BlendBindingParityTest {
@Test
fun blendBindingsMatchAcrossImports() {
val cmo3Files = System.getProperty("cmo3.probe")?.split(',')?.map(::File)?.filter { it.isFile }.orEmpty()
val moc3Root = System.getProperty("moc3.samples")?.let(::File)?.takeIf { it.isDirectory }
val pairs =
listOf("modelA", "modelB", "modelC").mapNotNull { prefix ->
val cmo3File = cmo3Files.firstOrNull { it.name.startsWith(prefix) } ?: return@mapNotNull null
val moc3File =
moc3Root?.walkTopDown()?.firstOrNull { it.isFile && it.name == "$prefix.moc3" } ?: return@mapNotNull null
prefix to (cmo3File to moc3File)
}
if (pairs.isEmpty()) {
println("cmo3.probe/moc3.samples not present; skipping blend-binding parity")
return
}
for ((name, files) in pairs) {
val (cmo3File, moc3File) = files
val cmo3Root = Cmo3.read(cmo3File).root as? CModelSource ?: error("$name: root is not a CModelSource")
// Both sides through the same canvas-space rewrite so mesh form deltas share a base.
val fromCmo3 = restMeshesToCanvasSpace(Cmo3Import.fromModelSource(cmo3Root))
val fromMoc3 = restMeshesToCanvasSpace(Moc3Import.fromMocDocument(Moc3.read(moc3File.readBytes()), null))
var meshBindingPairs = 0
var maxMeshDelta = 0f
var maxScalarDelta = 0f
val moc3DrawablesById = fromMoc3.drawables.associateBy { it.id }
for (cmo3Drawable in fromCmo3.drawables) {
val moc3Drawable = moc3DrawablesById[cmo3Drawable.id] ?: continue
meshBindingPairs +=
compareBindingLists(name, "drawable ${cmo3Drawable.id.raw}", cmo3Drawable.blendShapes, moc3Drawable.blendShapes) { cmo3Form, moc3Form ->
var maxComponentDelta = 0f
val componentCount = minOf(cmo3Form.positionDeltas.size, moc3Form.positionDeltas.size)
assertEquals(cmo3Form.positionDeltas.size, moc3Form.positionDeltas.size, "$name: mesh form size")
for (componentIndex in 0 until componentCount) {
maxComponentDelta =
maxOf(maxComponentDelta, abs(cmo3Form.positionDeltas[componentIndex] - moc3Form.positionDeltas[componentIndex]))
}
maxMeshDelta = maxOf(maxMeshDelta, maxComponentDelta)
maxScalarDelta = maxOf(maxScalarDelta, abs(cmo3Form.drawOrder - moc3Form.drawOrder))
maxScalarDelta = maxOf(maxScalarDelta, abs(cmo3Form.opacity - moc3Form.opacity))
}
}
// Warp/rotation correspondence via the parent chains of shared drawables (a moc names its
// deformers only by synthesized index, so ids cannot join directly).
var warpBindingPairs = 0
var rotationBindingPairs = 0
var maxControlPointDelta = 0f
var maxRotationDelta = 0f
val cmo3DeformersById = fromCmo3.deformers.associateBy { it.id }
val moc3DeformersById = fromMoc3.deformers.associateBy { it.id }
val comparedDeformerPairs = HashSet<Pair<Any, Any>>()
for (cmo3Drawable in fromCmo3.drawables) {
val moc3Drawable = moc3DrawablesById[cmo3Drawable.id] ?: continue
var cmo3ParentId = cmo3Drawable.parentDeformerId
var moc3ParentId = moc3Drawable.parentDeformerId
while (cmo3ParentId != null && moc3ParentId != null) {
val cmo3Deformer = cmo3DeformersById[cmo3ParentId] ?: break
val moc3Deformer = moc3DeformersById[moc3ParentId] ?: break
if (!comparedDeformerPairs.add(cmo3Deformer.id to moc3Deformer.id)) {
break
}
when (cmo3Deformer) {
is Deformer.Warp -> {
val moc3Warp = moc3Deformer as Deformer.Warp
warpBindingPairs +=
compareBindingLists(name, "warp ${cmo3Deformer.id.raw}", cmo3Deformer.blendShapes, moc3Warp.blendShapes) { cmo3Form, moc3Form ->
assertEquals(cmo3Form.controlPoints.size, moc3Form.controlPoints.size, "$name: warp form size")
for (componentIndex in cmo3Form.controlPoints.indices) {
maxControlPointDelta =
maxOf(maxControlPointDelta, abs(cmo3Form.controlPoints[componentIndex] - moc3Form.controlPoints[componentIndex]))
}
}
}
is Deformer.Rotation -> {
val moc3Rotation = moc3Deformer as Deformer.Rotation
rotationBindingPairs +=
compareBindingLists(name, "rotation ${cmo3Deformer.id.raw}", cmo3Deformer.blendShapes, moc3Rotation.blendShapes) { cmo3Form, moc3Form ->
maxRotationDelta = maxOf(maxRotationDelta, abs(cmo3Form.originX - moc3Form.originX))
maxRotationDelta = maxOf(maxRotationDelta, abs(cmo3Form.originY - moc3Form.originY))
maxRotationDelta = maxOf(maxRotationDelta, abs(cmo3Form.angle - moc3Form.angle))
maxRotationDelta = maxOf(maxRotationDelta, abs(cmo3Form.scale - moc3Form.scale))
}
}
}
cmo3ParentId = cmo3Deformer.parent
moc3ParentId = moc3Deformer.parent
}
}
println(
"[parity] $name: bindingPairs mesh=$meshBindingPairs warp=$warpBindingPairs rotation=$rotationBindingPairs " +
"maxMeshDelta=$maxMeshDelta maxScalarDelta=$maxScalarDelta " +
"maxControlPointDelta=$maxControlPointDelta maxRotationDelta=$maxRotationDelta",
)
assertTrue(meshBindingPairs + warpBindingPairs + rotationBindingPairs > 0, "$name: compared some bindings")
// Ceilings pinned from the first measured run: maxMeshDelta 0.352 px (Model A) / 0.204
// (Model C), maxControlPointDelta 1.3e-4, maxRotationDelta 2.5e-4, scalar deltas exactly
// 0 - the reconstruction is sub-pixel across the corpus, so the ceilings sit just above
// the measured float-noise class and reject any space or reference-frame regression
// outright.
assertTrue(maxMeshDelta <= 1f, "$name: mesh form parity ceiling (got $maxMeshDelta)")
assertTrue(maxScalarDelta <= 0.001f, "$name: scalar form parity ceiling (got $maxScalarDelta)")
assertTrue(maxControlPointDelta <= 0.001f, "$name: warp cp parity ceiling (got $maxControlPointDelta)")
assertTrue(maxRotationDelta <= 0.01f, "$name: rotation parity ceiling (got $maxRotationDelta)")
}
}
/**
* Compares two binding lists on one object: structural identity (driving parameters, keys,
* neutral index, limit curves, null pattern) asserted exactly; each non-neutral form pair is
* handed to [compareForms] for value measurement.
*
* @param String modelName The corpus model (for messages).
* @param String objectLabel The object under comparison (for messages).
* @param List cmo3Bindings The CMO3-imported bindings.
* @param List moc3Bindings The MOC3-imported bindings.
* @param Function compareForms Per-form value comparator.
* @return Int The number of binding pairs compared.
*/
private fun <TForm : Any> compareBindingLists(
modelName: String,
objectLabel: String,
cmo3Bindings: List<BlendShapeBinding<TForm>>,
moc3Bindings: List<BlendShapeBinding<TForm>>,
compareForms: (TForm, TForm) -> Unit,
): Int {
assertEquals(cmo3Bindings.size, moc3Bindings.size, "$modelName: binding count on $objectLabel")
val moc3ByParameter = moc3Bindings.associateBy { it.parameterId }
for (cmo3Binding in cmo3Bindings) {
val moc3Binding = moc3ByParameter[cmo3Binding.parameterId]
assertTrue(moc3Binding != null, "$modelName: $objectLabel missing moc3 binding for ${cmo3Binding.parameterId.raw}")
assertEquals(
cmo3Binding.keys.toList(),
moc3Binding.keys.toList(),
"$modelName: keys on $objectLabel/${cmo3Binding.parameterId.raw}",
)
assertEquals(
cmo3Binding.neutralIndex,
moc3Binding.neutralIndex,
"$modelName: neutral index on $objectLabel/${cmo3Binding.parameterId.raw}",
)
assertEquals(
cmo3Binding.forms.map { it == null },
moc3Binding.forms.map { it == null },
"$modelName: form null pattern on $objectLabel/${cmo3Binding.parameterId.raw}",
)
assertEquals(
cmo3Binding.limits.map { limit -> limit.parameterId to limit.points }.sortedBy { it.first.raw },
moc3Binding.limits.map { limit -> limit.parameterId to limit.points }.sortedBy { it.first.raw },
"$modelName: limit curves on $objectLabel/${cmo3Binding.parameterId.raw}",
)
for (formIndex in cmo3Binding.forms.indices) {
val cmo3Form = cmo3Binding.forms[formIndex]
val moc3Form = moc3Binding.forms[formIndex]
if (cmo3Form != null && moc3Form != null) {
compareForms(cmo3Form, moc3Form)
}
}
}
return cmo3Bindings.size
}
}
@@ -0,0 +1,250 @@
package org.umamo.render
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.moc3.Moc3
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.interop.moc3.import.Moc3Import
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.PuppetModel
import java.io.File
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
// Offscreen channels are stored as plain f32 on both sides (no quantization like keyform
// coordinates), so the parity bar is tight.
private const val SCALAR_TOLERANCE = 0.001f
/**
* Imports the offscreen corpus pairs from their `.cmo3` source and baked `.moc3` and asserts the
* composite surface agrees across the two paths: part composite state (composition enums, clip
* lists, invert, static channels), the keyformed opacity/color cells, and the drawable-level
* extended blend + culling. The offscreen counterpart of [Moc3Cmo3ParityTest]. Skips gracefully
* without the corpus.
*/
class CompositeImportParityTest {
private val pairNames = listOf("ModelWithOffscreenPartClipping", "MultiplyScreenColors", "modelA")
private fun cmo3ByBasename(): Map<String, File> =
System.getProperty("cmo3.probe")
?.split(',')
?.map(::File)
?.filter { it.isFile }
?.associateBy { it.name.removeSuffix(".cmo3") }
?: emptyMap()
private fun moc3ByBasename(): Map<String, File> =
System.getProperty("moc3.samples")
?.let(::File)
?.takeIf { it.isDirectory }
?.walkTopDown()
?.filter { it.isFile && it.extension == "moc3" }
?.associateBy { it.name.removeSuffix(".moc3") }
?: emptyMap()
private fun assertColorClose(expected: ColorRgb, actual: ColorRgb, label: String) {
assertTrue(
abs(expected.red - actual.red) < SCALAR_TOLERANCE &&
abs(expected.green - actual.green) < SCALAR_TOLERANCE &&
abs(expected.blue - actual.blue) < SCALAR_TOLERANCE,
"$label: expected $expected, got $actual",
)
}
/**
* Asserts the two imports' per-channel part tracks agree cell for cell.
*
* Compares each channel's own track rather than one bundled cell: after the fan-out the channels are
* independent tracks, and comparing them separately is what would catch a fan-out that mis-routed one
* channel's values into another's.
*/
private fun assertChannelTracksMatch(cmo3Channels: ChannelGrids, moc3Channels: ChannelGrids, label: String) {
for (channel in listOf(FormChannel.OPACITY, FormChannel.MULTIPLY_COLOR, FormChannel.SCREEN_COLOR)) {
val cmo3Track = cmo3Channels[channel] ?: continue
val moc3Track = moc3Channels[channel] ?: continue
assertEquals(cmo3Track.axes.size, moc3Track.axes.size, "$label: $channel axis count")
assertEquals(cmo3Track.cells.size, moc3Track.cells.size, "$label: $channel cell count")
val moc3ByCoordinate = moc3Track.cells.associateBy { cell -> cell.coordinate.toList() }
for (cmo3Cell in cmo3Track.cells) {
val coordinate = cmo3Cell.coordinate.toList()
val moc3Cell = assertNotNull(moc3ByCoordinate[coordinate], "$label: $channel cell $coordinate present in moc3")
val cmo3Value = cmo3Cell.form
val moc3Value = moc3Cell.form
if (cmo3Value is ChannelValue.Scalar && moc3Value is ChannelValue.Scalar) {
assertTrue(
abs(cmo3Value.value - moc3Value.value) < SCALAR_TOLERANCE,
"$label: $channel at $coordinate (${cmo3Value.value} vs ${moc3Value.value})",
)
} else if (cmo3Value is ChannelValue.Color && moc3Value is ChannelValue.Color) {
assertColorClose(cmo3Value.color, moc3Value.color, "$label: $channel at $coordinate")
} else {
assertEquals(cmo3Value, moc3Value, "$label: $channel kind at $coordinate")
}
}
}
}
private fun assertCompositeParity(cmo3Puppet: PuppetModel, moc3Puppet: PuppetModel, pairName: String) {
val cmo3Parts = cmo3Puppet.parts.associateBy { it.id }
var comparedComposites = 0
for (moc3Part in moc3Puppet.parts) {
// The bake drops sketch parts; iterate the moc side, which must be a subset.
val cmo3Part = assertNotNull(cmo3Parts[moc3Part.id], "$pairName: moc part ${moc3Part.id.raw} in cmo3")
// Compare the applied composite (active only while Isolated): both import paths agree there. The
// stored latent composite differs by design off-Isolated (CMO3 captures authored fields, MOC3 has
// none), so parity is asserted on activeComposite, not the always-present stored composite.
val moc3Composite = moc3Part.activeComposite
val cmo3Composite = cmo3Part.activeComposite
assertEquals(cmo3Composite != null, moc3Composite != null, "$pairName: composite presence of ${moc3Part.id.raw}")
if (cmo3Composite == null || moc3Composite == null) {
continue
}
comparedComposites++
val partLabel = "$pairName: ${moc3Part.id.raw}"
assertEquals(cmo3Composite.blendMode, moc3Composite.blendMode, "$partLabel color blend")
assertEquals(cmo3Composite.alphaBlendMode, moc3Composite.alphaBlendMode, "$partLabel alpha blend")
assertEquals(cmo3Composite.invertMask, moc3Composite.invertMask, "$partLabel invert mask")
assertEquals(cmo3Composite.maskedBy.toSet(), moc3Composite.maskedBy.toSet(), "$partLabel clip list")
assertTrue(
abs(cmo3Composite.opacity - moc3Composite.opacity) < SCALAR_TOLERANCE,
"$partLabel static opacity (${cmo3Composite.opacity} vs ${moc3Composite.opacity})",
)
assertColorClose(cmo3Composite.multiplyColor, moc3Composite.multiplyColor, "$partLabel static multiply")
assertColorClose(cmo3Composite.screenColor, moc3Composite.screenColor, "$partLabel static screen")
// Keyformed channels: comparable only when both sides carry parameter-driven tracks (a static
// moc part stores none, while the cmo3 may keep a degenerate zero-axis one).
if (!cmo3Part.channelGrids.isEmpty && !moc3Part.channelGrids.isEmpty) {
assertChannelTracksMatch(cmo3Part.channelGrids, moc3Part.channelGrids, partLabel)
}
}
assertTrue(comparedComposites > 0, "$pairName: compared at least one isolated part")
val cmo3Drawables = cmo3Puppet.drawables.associateBy { it.id }
for (moc3Drawable in moc3Puppet.drawables) {
val cmo3Drawable = assertNotNull(cmo3Drawables[moc3Drawable.id], "$pairName: moc drawable ${moc3Drawable.id.raw} in cmo3")
val drawableLabel = "$pairName: ${moc3Drawable.id.raw}"
assertEquals(cmo3Drawable.blendMode, moc3Drawable.blendMode, "$drawableLabel color blend")
assertEquals(cmo3Drawable.alphaBlendMode, moc3Drawable.alphaBlendMode, "$drawableLabel alpha blend")
assertEquals(cmo3Drawable.culling, moc3Drawable.culling, "$drawableLabel culling")
}
}
/**
* The DISTINCT non-identity deformer render channel values in [puppet], sorted and rounded.
*
* A value set rather than a per-deformer join because the two import paths do not share deformer
* ids - MOC3 synthesizes `Deformer<n>` from file order while CMO3 carries the authored id - so
* there is nothing to join on.
*
* DISTINCT rather than a multiset because the two files legitimately store different keyform
* COUNTS for the same rig: baking resamples the grid (one corpus model carries 191 warp keyforms
* in its .cmo3 and 436 in its .moc3). Multiplicity is therefore not a parity claim; the set of
* authored values is. That still catches what matters - a path that drops the channels yields an
* empty set, and one that mis-scales a value yields a different member.
*
* @param PuppetModel puppet The imported rig.
* @return List<String> Sorted distinct "opacity|multiply|screen" rows.
*/
private fun deformerChannelMultiset(puppet: PuppetModel): List<String> {
fun row(opacity: Float, multiplyColor: ColorRgb, screenColor: ColorRgb): String? {
if (opacity == 1f && multiplyColor == ColorRgb.MultiplyIdentity && screenColor == ColorRgb.ScreenIdentity) {
return null
}
// Rounded: the two paths reach the same values through different float arithmetic (CMO3
// parses decimal text, MOC3 reads stored f32), so exact equality is the wrong bar.
fun round(value: Float): String = ((value * 10000f).toInt() / 10000f).toString()
return "op=${round(opacity)} " +
"mul=${round(multiplyColor.red)},${round(multiplyColor.green)},${round(multiplyColor.blue)} " +
"scr=${round(screenColor.red)},${round(screenColor.green)},${round(screenColor.blue)}"
}
// Zip the three channel tracks back together by cell so the comparison stays a per-cell
// (opacity, multiply, screen) row - the tracks share a shape, so index N means the same cell in all
// three.
fun channelRows(channels: ChannelGrids): List<String> {
val opacities = channels[FormChannel.OPACITY]?.cells.orEmpty().map { cell -> (cell.form as? ChannelValue.Scalar)?.value ?: 1f }
val multiplies =
channels[FormChannel.MULTIPLY_COLOR]?.cells.orEmpty().map { cell ->
(cell.form as? ChannelValue.Color)?.color ?: ColorRgb.MultiplyIdentity
}
val screens =
channels[FormChannel.SCREEN_COLOR]?.cells.orEmpty().map { cell ->
(cell.form as? ChannelValue.Color)?.color ?: ColorRgb.ScreenIdentity
}
return opacities.indices.mapNotNull { cellIndex ->
row(
opacities[cellIndex],
multiplies.getOrElse(cellIndex) { ColorRgb.MultiplyIdentity },
screens.getOrElse(cellIndex) { ColorRgb.ScreenIdentity },
)
}
}
return puppet.deformers
.flatMap { deformer -> channelRows(deformer.channelGrids) }
.distinct()
.sorted()
}
@Test
fun deformerRenderChannelsAgreeAcrossImports() {
val cmo3Files = cmo3ByBasename()
val moc3Files = moc3ByBasename()
var comparedPairs = 0
var totalChannelledKeyforms = 0
// The corpus models that actually author a deformer channel and have both halves of a pair.
for (pairName in listOf("modelA", "modelC", "modelE")) {
val cmo3File = cmo3Files[pairName] ?: continue
val moc3File = moc3Files[pairName] ?: continue
val cmo3Root = Cmo3.read(cmo3File).root as? CModelSource ?: error("$pairName: root is not a CModelSource")
val cmo3Channels = deformerChannelMultiset(Cmo3Import.fromModelSource(cmo3Root))
val moc3Channels = deformerChannelMultiset(Moc3Import.fromMocDocument(Moc3.read(moc3File.readBytes()), null))
assertEquals(cmo3Channels, moc3Channels, "$pairName: deformer render channels")
assertTrue(cmo3Channels.isNotEmpty(), "$pairName: authors at least one non-identity deformer channel")
// The anchor that matters: a deformer opacity of exactly 0 is the subtree show/hide switch
// riggers use, and dropping it renders whole effect subtrees permanently visible.
assertTrue(
cmo3Channels.any { it.startsWith("op=0.0 ") },
"$pairName: a deformer keys opacity to 0 (the subtree hide switch)",
)
totalChannelledKeyforms += cmo3Channels.size
comparedPairs++
println("[Umamo][deformer-channel-parity] $pairName: ${cmo3Channels.size} distinct non-identity channel values agree")
}
if (comparedPairs == 0) {
println("no deformer-channel cmo3/moc3 pairs present; skipping")
} else {
assertTrue(totalChannelledKeyforms > 0, "compared at least one channelled keyform")
}
}
@Test
fun compositeSurfaceAgreesAcrossImports() {
val cmo3Files = cmo3ByBasename()
val moc3Files = moc3ByBasename()
var comparedPairs = 0
for (pairName in pairNames) {
val cmo3File = cmo3Files[pairName]
val moc3File = moc3Files[pairName]
if (cmo3File == null || moc3File == null) {
println("$pairName cmo3/moc3 pair not present; skipping")
continue
}
val cmo3Root = Cmo3.read(cmo3File).root as? CModelSource ?: error("$pairName: root is not a CModelSource")
val cmo3Puppet = Cmo3Import.fromModelSource(cmo3Root)
val moc3Puppet = Moc3Import.fromMocDocument(Moc3.read(moc3File.readBytes()), null)
assertCompositeParity(cmo3Puppet, moc3Puppet, pairName)
comparedPairs++
println("[Umamo][composite-parity] $pairName: parts=${moc3Puppet.parts.size} drawables=${moc3Puppet.drawables.size} OK")
}
if (comparedPairs == 0) {
println("no composite cmo3/moc3 pairs present; skipping")
}
}
}
@@ -0,0 +1,125 @@
package org.umamo.render
import org.junit.Assume
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.interop.cmo3.cmo3AtlasPages
import java.io.File
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
/**
* A page Umamo composes from a CMO3's tiles and placements shows what the editor's own page shows.
*
* The derivation is what every atlas change leaves the document drawing - a reload, a replace, an add,
* a repack all re-derive the WHOLE page from each tile's raster - and what a CMO3 export then writes
* back. So an unedited atlas, derived, must come back as the page the file holds: nothing painted
* where the editor's page is transparent (meshes reach past their art, and anything painted there
* shows as a fringe), and every edge resampled the way the editor resamples it, bilinearly against
* the transparency beyond the art, so its coverage matches to a few steps of alpha.
*
* Gated on `cmo3.sample` (Erica by default: one 8192 page, 176 tiles whose rasters are cropped tight to
* their art, 84 of them at fractional positions); skips by assumption without it.
*/
class DerivedAtlasPageFidelityTest {
private companion object {
/** Below this alpha a file pixel counts as empty page. */
const val EMPTY_ALPHA = 16
/** At or above this alpha a derived pixel counts as painted. */
const val PAINTED_ALPHA = 64
/** The most a derived pixel's alpha may differ from the file's: resampling rounds, it never moves an edge. */
const val ALPHA_TOLERANCE = 8
/** At or above this alpha on both pages a pixel's color is compared. */
const val COLOR_COMPARED_ALPHA = 128
/** How far a compared pixel's color may sit from the file's before it counts as different. */
const val COLOR_TOLERANCE = 24
/**
* The share of compared pixels whose color may differ past [COLOR_TOLERANCE]. The editor's own
* translucent edge texels run slightly darker than the art's color, where the derivation keeps the
* art's color; a handful of edge pixels differ that way and nothing else does.
*/
const val MAXIMUM_COLOR_MISMATCH_FRACTION = 1e-4f
}
private val sample: File? = System.getProperty("cmo3.sample")?.let(::File)?.takeIf { file -> file.isFile }
@Test
fun anUneditedAtlasDerivesBackToTheFilesOwnPages() {
val file = sample
Assume.assumeTrue("[derived-page] no cmo3.sample", file != null)
val cmo3 = Cmo3.read(file!!)
val root = cmo3.root as CModelSource
val imported = Cmo3Import.importModelSource(root)
val puppet = imported.puppet
Assume.assumeTrue("[derived-page] ${file.name} draws from its source layers, not pages", puppet.atlas.storedUvsAddressPages)
val tileResources = imported.atlasIngest.imageResourceByTile
val rasters = SourceArtRasters.fromPng { tileId -> tileResources[tileId]?.let(cmo3::extractLayerPng) }
val derived = assertNotNull(deriveAtlasTextures(puppet, rasters, premultipliedAlpha = false), "the atlas derives")
val filePages = cmo3AtlasPages(root, cmo3::extractLayerPng)
var comparedPages = 0
val failures = ArrayList<String>()
for (pageIndex in puppet.atlas.pages.indices) {
// The file's page for this model page: the one a drawable over a tile placed here samples.
val drawable =
puppet.drawables.firstOrNull { candidate ->
candidate.atlasTileId?.let { tileId -> puppet.atlas.tileById[tileId]?.placement?.pageIndex } == pageIndex &&
filePages.atlasIndexByDrawableId.containsKey(candidate.id.raw)
} ?: continue
val filePage: RasterImage = PngCodec.read(filePages.pageBytes[filePages.atlasIndexByDrawableId.getValue(drawable.id.raw)])
val derivedPage = derived.atlases[pageIndex]
if (filePage.width != derivedPage.width || filePage.height != derivedPage.height) {
failures.add("page $pageIndex: the file's is ${filePage.width}x${filePage.height}, derived ${derivedPage.width}x${derivedPage.height}")
continue
}
comparedPages++
var paintedOverEmpty = 0
var maximumAlphaDifference = 0
var colorCompared = 0
var colorMismatches = 0
for (pixelIndex in 0 until filePage.width * filePage.height) {
val byteOffset = pixelIndex * 4
val fileAlpha = filePage.rgba[byteOffset + 3].toInt() and 0xFF
val derivedAlpha = derivedPage.rgba[byteOffset + 3].toInt() and 0xFF
if (fileAlpha < EMPTY_ALPHA && derivedAlpha >= PAINTED_ALPHA) {
paintedOverEmpty++
}
maximumAlphaDifference = maxOf(maximumAlphaDifference, abs(fileAlpha - derivedAlpha))
if (fileAlpha >= COLOR_COMPARED_ALPHA && derivedAlpha >= COLOR_COMPARED_ALPHA) {
colorCompared++
val colorDifference =
(0 until 3).maxOf { channel -> abs((filePage.rgba[byteOffset + channel].toInt() and 0xFF) - (derivedPage.rgba[byteOffset + channel].toInt() and 0xFF)) }
if (colorDifference > COLOR_TOLERANCE) {
colorMismatches++
}
}
}
val colorMismatchFraction = if (colorCompared == 0) 0f else colorMismatches.toFloat() / colorCompared
println(
"[derived-page] ${file.name} page $pageIndex: $paintedOverEmpty pixels painted over empty page, alpha within $maximumAlphaDifference, " +
"$colorMismatches of $colorCompared compared pixels off by more than $COLOR_TOLERANCE in color",
)
if (paintedOverEmpty > 0) {
failures.add("page $pageIndex: $paintedOverEmpty pixels painted where the file's page is empty")
}
if (maximumAlphaDifference > ALPHA_TOLERANCE) {
failures.add("page $pageIndex: a pixel's alpha differs from the file's by $maximumAlphaDifference")
}
if (colorMismatchFraction > MAXIMUM_COLOR_MISMATCH_FRACTION) {
failures.add("page $pageIndex: $colorMismatchFraction of compared pixels differ in color from the file's")
}
}
assertTrue(comparedPages > 0, "no page was compared; the gate checked nothing")
assertTrue(failures.isEmpty(), "the derived pages differ from the file's own:\n" + failures.joinToString("\n"))
}
}
@@ -0,0 +1,484 @@
package org.umamo.render
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.json.Cdi3Json
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.interop.moc3.import.Moc3Import
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshDeltaForm
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RenderDrawable
import org.umamo.runtime.model.RenderGroup
import org.umamo.runtime.model.RenderNode
import java.io.File
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
// CMO3 stores keyform coordinates lightly quantized (dyadic fractions, ~1e-4) where the moc keeps
// full precision, so parity is bounded, not exact. Canvas-pixel values agree within a pixel: the
// quantization amplifies through a warp lattice spanning thousands of pixels (corpus max observed
// 0.68px over 30k vertices; a wrong space conversion is off by hundreds). Warp-lattice (u, v)
// values compare pre-amplification, within ~1e-4 of the unit lattice.
private const val CANVAS_TOLERANCE_PX = 1.0f
private const val LATTICE_TOLERANCE = 0.001f
private const val ANGLE_TOLERANCE_DEGREES = 0.05f
/**
* Imports the same model from its `.cmo3` source and its baked `.moc3` (with the rest-mesh post-pass
* the document loader applies) and asserts the two `PuppetModel`s agree - the gate that pins the MOC3
* coordinate conversion (CanvasInfo root transform, rotation-local scaling, the rotation angle sign,
* and the canvas-space rest-mesh rewrite) against the CMO3 numbers, which the differential-oracle
* test already validates end-to-end.
*
* Gated on BOTH `-Dcmo3.sample` and `-Dmoc3.sample` naming the same model (the build supplies the
* local corpus Erica for both by default). Comparison runs over the drawable-id intersection: the
* bake drops sketch ("Guide Image") parts and their drawables, so the sets are not equal.
*/
class Moc3Cmo3ParityTest {
private val cmo3Sample: File? = System.getProperty("cmo3.sample")?.let(::File)?.takeIf { it.isFile }
private val moc3Sample: File? = System.getProperty("moc3.sample")?.let(::File)?.takeIf { it.isFile }
@Test
fun mocImportMatchesCmo3Import() {
val cmo3File = cmo3Sample
val moc3File = moc3Sample
if (cmo3File == null || moc3File == null) {
println("cmo3.sample/moc3.sample not present; skipping parity test")
return
}
val cmo3Root = Cmo3.read(cmo3File).root as? CModelSource ?: error("root is not a CModelSource")
// The rest-mesh comparison normalizes BOTH sides through the same default-pose rewrite: CMO3's
// stored base is authored editing geometry that may drift a few pixels from the evaluated default
// pose (a moc has no way to recover the authored value), so comparing raw cmo3 bases against the
// moc's evaluated ones would measure that drift, not the conversion under test.
val fromCmo3 = restMeshesToCanvasSpace(Cmo3Import.fromModelSource(cmo3Root))
val fromMoc3 =
restMeshesToCanvasSpace(
Moc3Import.fromMocDocument(Moc3.read(moc3File.readBytes()), siblingDisplayInfo(moc3File)),
)
// Canvas and world origin agree (CanvasInfo origin == CMO3 canvas center).
assertEquals(fromCmo3.canvasWidth, fromMoc3.canvasWidth, "canvas width")
assertEquals(fromCmo3.canvasHeight, fromMoc3.canvasHeight, "canvas height")
assertEquals(fromCmo3.worldOriginX, fromMoc3.worldOriginX, "world origin x")
assertEquals(fromCmo3.worldOriginZ, fromMoc3.worldOriginZ, "world origin y")
// Parameters: identical axes (the bake preserves every parameter).
val cmo3Parameters = fromCmo3.parameters.associateBy { it.id }
for (mocParameter in fromMoc3.parameters) {
val cmo3Parameter = cmo3Parameters[mocParameter.id] ?: error("moc parameter ${mocParameter.id.raw} not in cmo3")
assertEquals(cmo3Parameter.min, mocParameter.min, "min of ${mocParameter.id.raw}")
assertEquals(cmo3Parameter.max, mocParameter.max, "max of ${mocParameter.id.raw}")
assertEquals(cmo3Parameter.default, mocParameter.default, "default of ${mocParameter.id.raw}")
}
assertEquals(fromCmo3.parameterLinks, fromMoc3.parameterLinks, "parameter links")
val cmo3Drawables = fromCmo3.drawables.associateBy { it.id }
val moc3Drawables = fromMoc3.drawables.associateBy { it.id }
val sharedIds = cmo3Drawables.keys.intersect(moc3Drawables.keys)
println("[Umamo][parity] drawables cmo3=${cmo3Drawables.size} moc3=${moc3Drawables.size} shared=${sharedIds.size}")
assertTrue(sharedIds.size >= moc3Drawables.size, "every moc3 drawable should exist in the cmo3")
// Keyform-space tolerance per drawable: warp children live on the unit lattice, everything else
// in canvas pixels.
val moc3DeformerById = fromMoc3.deformers.associateBy { it.id }
fun keyformTolerance(parentDeformerId: DeformerId?): Float =
if (parentDeformerId != null && moc3DeformerById[parentDeformerId] is Deformer.Warp) LATTICE_TOLERANCE else CANVAS_TOLERANCE_PX
var comparedVertices = 0
var maxRestDelta = 0f
val restOffenders = ArrayList<String>()
for (drawableId in sharedIds) {
val cmo3Drawable = cmo3Drawables.getValue(drawableId)
val moc3Drawable = moc3Drawables.getValue(drawableId)
assertEquals(cmo3Drawable.blendMode, moc3Drawable.blendMode, "blend mode of ${drawableId.raw}")
assertEquals(cmo3Drawable.maskedBy.toSet(), moc3Drawable.maskedBy.toSet(), "masks of ${drawableId.raw}")
assertEquals(cmo3Drawable.invertMask, moc3Drawable.invertMask, "invert mask of ${drawableId.raw}")
val cmo3Mesh = cmo3Drawable.mesh ?: continue
val moc3Mesh = moc3Drawable.mesh ?: error("moc3 ${drawableId.raw} has no mesh but the cmo3 does")
assertEquals(cmo3Mesh.vertexCount, moc3Mesh.vertexCount, "vertex count of ${drawableId.raw}")
assertTrue(cmo3Mesh.indices.contentEquals(moc3Mesh.indices), "triangle indices of ${drawableId.raw}")
// UVs are static in both formats and untouched by the coordinate conversion.
assertTrue(
floatsClose(cmo3Mesh.uvs, moc3Mesh.uvs, 0.0005f),
"uvs of ${drawableId.raw}" + flipDiagnostic(cmo3Mesh.uvs, moc3Mesh.uvs),
)
// Rest positions: canvas space on both sides (the moc side through the default-pose rewrite),
// so this pins the whole conversion + cascade path. Collected first (worst offender per
// drawable) so a failure reports the model-wide picture, not the first vertex hit.
assertEquals(cmo3Mesh.positions.size, moc3Mesh.positions.size, "position array of ${drawableId.raw}")
var drawableWorstDelta = 0f
var drawableWorstIndex = -1
for (coordIndex in cmo3Mesh.positions.indices) {
val delta = abs(cmo3Mesh.positions[coordIndex] - moc3Mesh.positions[coordIndex])
if (delta > drawableWorstDelta) {
drawableWorstDelta = delta
drawableWorstIndex = coordIndex
}
}
if (drawableWorstDelta > maxRestDelta) {
maxRestDelta = drawableWorstDelta
}
if (drawableWorstDelta > CANVAS_TOLERANCE_PX) {
restOffenders.add(
"${drawableId.raw}[$drawableWorstIndex] delta=$drawableWorstDelta " +
"cmo3=${cmo3Mesh.positions[drawableWorstIndex]} moc3=${moc3Mesh.positions[drawableWorstIndex]}",
)
}
comparedVertices += cmo3Mesh.vertexCount
compareMeshKeyforms(
drawableId,
cmo3Drawable.geometryGrid,
cmo3Mesh.positions,
moc3Drawable.geometryGrid,
moc3Mesh.positions,
keyformTolerance(moc3Drawable.parentDeformerId),
)
compareMeshChannels(drawableId, cmo3Drawable.channelGrids, moc3Drawable.channelGrids)
}
println("[Umamo][parity] compared $comparedVertices rest vertices, max delta $maxRestDelta px")
assertTrue(
restOffenders.isEmpty(),
"rest positions beyond ${CANVAS_TOLERANCE_PX}px on ${restOffenders.size} drawables:\n" +
restOffenders.take(20).joinToString("\n"),
)
compareDeformerChains(fromCmo3, fromMoc3, sharedIds)
compareRenderOrder(fromCmo3, fromMoc3, sharedIds)
}
/**
* Compares two mesh keyform grids cell by cell as parent-space absolutes (base + delta), matching
* cells across the grids by their axis coordinate. Skips silently when either side is unkeyed.
*
* @param DrawableId drawableId The drawable under comparison (for failure messages).
* @param KeyformGrid? cmo3Grid The CMO3 grid (deltas vs [cmo3Base]).
* @param FloatArray cmo3Base The CMO3 rest positions.
* @param KeyformGrid? moc3Grid The MOC3 grid (deltas vs [moc3Base]).
* @param FloatArray moc3Base The MOC3 rest positions.
* @param Float tolerance The per-coordinate tolerance in the drawable's parent space.
*/
private fun compareMeshKeyforms(
drawableId: DrawableId,
cmo3Grid: KeyformGrid<MeshDeltaForm>?,
cmo3Base: FloatArray,
moc3Grid: KeyformGrid<MeshDeltaForm>?,
moc3Base: FloatArray,
tolerance: Float,
) {
if (cmo3Grid == null || moc3Grid == null) {
return
}
val cmo3Axes = cmo3Grid.axes.map { axis -> axis.parameterId to axis.keys.toList() }
val moc3Axes = moc3Grid.axes.map { axis -> axis.parameterId to axis.keys.toList() }
assertEquals(cmo3Axes, moc3Axes, "keyform axes of ${drawableId.raw}")
val moc3Cells = moc3Grid.cells.associateBy { cell -> cell.coordinate.toList() }
for (cmo3Cell in cmo3Grid.cells) {
val moc3Cell = moc3Cells[cmo3Cell.coordinate.toList()] ?: error("moc3 ${drawableId.raw} misses cell ${cmo3Cell.coordinate.toList()}")
val cmo3Deltas = cmo3Cell.form.positionDeltas
val moc3Deltas = moc3Cell.form.positionDeltas
assertEquals(cmo3Deltas.size, moc3Deltas.size, "delta array of ${drawableId.raw}")
for (coordIndex in cmo3Deltas.indices) {
val cmo3Absolute = cmo3Base[coordIndex] + cmo3Deltas[coordIndex]
val moc3Absolute = moc3Base[coordIndex] + moc3Deltas[coordIndex]
assertTrue(
abs(cmo3Absolute - moc3Absolute) <= tolerance,
"keyform position of ${drawableId.raw}@${cmo3Cell.coordinate.toList()}[$coordIndex]: " +
"cmo3=$cmo3Absolute moc3=$moc3Absolute",
)
}
}
}
/**
* Asserts the two import paths agree on a drawable's scalar channel tracks, cell for cell.
*
* Draw order and opacity used to ride the geometry cell, so they were compared there; they are their
* own tracks now, but the parity claim is unchanged - both paths must land on the same values.
*
* @param DrawableId drawableId The drawable under comparison (for failure messages).
* @param ChannelGrids cmo3Channels The CMO3 import's tracks.
* @param ChannelGrids moc3Channels The MOC3 import's tracks.
*/
private fun compareMeshChannels(drawableId: DrawableId, cmo3Channels: ChannelGrids, moc3Channels: ChannelGrids) {
for (channel in listOf(FormChannel.DRAW_ORDER, FormChannel.OPACITY)) {
val cmo3Track = cmo3Channels[channel] ?: continue
val moc3Track = moc3Channels[channel] ?: continue
val moc3Cells = moc3Track.cells.associateBy { cell -> cell.coordinate.toList() }
for (cmo3Cell in cmo3Track.cells) {
val coordinate = cmo3Cell.coordinate.toList()
val moc3Cell = moc3Cells[coordinate] ?: error("moc3 ${drawableId.raw} misses $channel cell $coordinate")
val cmo3Value = (cmo3Cell.form as ChannelValue.Scalar).value
val moc3Value = (moc3Cell.form as ChannelValue.Scalar).value
assertTrue(
abs(cmo3Value - moc3Value) <= 0.001f,
"$channel of ${drawableId.raw}@$coordinate: cmo3=$cmo3Value moc3=$moc3Value",
)
}
}
}
/**
* Compares the deformer chains above each shared drawable. MOC3 deformers carry synthesized ids,
* so they are matched positionally along the parent chain from each drawable, then compared by
* kind, lattice size, keyform axes, and keyform values - warp control points in the parent's space
* (lattice for a nested warp, canvas pixels at the root), rotation origin/scale/reflection
* likewise, and the total angle within [ANGLE_TOLERANCE_DEGREES] (this is what pins the angle-sign
* conversion).
*
* @param PuppetModel fromCmo3 The CMO3-imported model.
* @param PuppetModel fromMoc3 The MOC3-imported model.
* @param Set<DrawableId> sharedIds The drawable-id intersection.
*/
private fun compareDeformerChains(fromCmo3: PuppetModel, fromMoc3: PuppetModel, sharedIds: Set<DrawableId>) {
val cmo3Deformers = fromCmo3.deformers.associateBy { it.id }
val moc3Deformers = fromMoc3.deformers.associateBy { it.id }
val cmo3Drawables = fromCmo3.drawables.associateBy { it.id }
val moc3Drawables = fromMoc3.drawables.associateBy { it.id }
val comparedPairs = HashSet<Pair<DeformerId, DeformerId>>()
var maxAngleDelta = 0f
for (drawableId in sharedIds) {
var cmo3Parent = cmo3Drawables.getValue(drawableId).parentDeformerId
var moc3Parent = moc3Drawables.getValue(drawableId).parentDeformerId
while (cmo3Parent != null || moc3Parent != null) {
assertTrue(
cmo3Parent != null && moc3Parent != null,
"deformer chain of ${drawableId.raw} diverges: cmo3=${cmo3Parent?.raw} moc3=${moc3Parent?.raw}",
)
val cmo3Deformer = cmo3Deformers.getValue(cmo3Parent)
val moc3Deformer = moc3Deformers.getValue(moc3Parent)
if (!comparedPairs.add(cmo3Deformer.id to moc3Deformer.id)) {
break
}
// A nested deformer's own keyform space is ITS parent's space.
val spaceTolerance =
if (moc3Deformer.parent != null && moc3Deformers[moc3Deformer.parent] is Deformer.Warp) LATTICE_TOLERANCE else CANVAS_TOLERANCE_PX
when (cmo3Deformer) {
is Deformer.Warp -> {
val mocWarp = moc3Deformer as? Deformer.Warp ?: error("kind mismatch above ${drawableId.raw}")
assertEquals(cmo3Deformer.rows, mocWarp.rows, "warp rows above ${drawableId.raw}")
assertEquals(cmo3Deformer.columns, mocWarp.columns, "warp columns above ${drawableId.raw}")
assertEquals(cmo3Deformer.isQuadTransform, mocWarp.isQuadTransform, "warp mode above ${drawableId.raw}")
compareWarpGrids(drawableId, cmo3Deformer.geometryGrid, mocWarp.geometryGrid, spaceTolerance)
}
is Deformer.Rotation -> {
val mocRotation = moc3Deformer as? Deformer.Rotation ?: error("kind mismatch above ${drawableId.raw}")
val angleDelta = compareRotationGrids(drawableId, cmo3Deformer, mocRotation, spaceTolerance)
if (angleDelta > maxAngleDelta) {
maxAngleDelta = angleDelta
}
}
}
cmo3Parent = cmo3Deformer.parent
moc3Parent = moc3Deformer.parent
}
}
println("[Umamo][parity] compared ${comparedPairs.size} deformer pairs, max angle delta $maxAngleDelta deg")
}
/**
* Compares two warp keyform grids cell by cell (control points in the warp's parent space).
*
* @param DrawableId drawableId The drawable whose chain is under comparison (for messages).
* @param KeyformGrid? cmo3Grid The CMO3 warp grid.
* @param KeyformGrid? moc3Grid The MOC3 warp grid.
* @param Float tolerance The per-coordinate tolerance in the warp's parent space.
*/
private fun compareWarpGrids(
drawableId: DrawableId,
cmo3Grid: KeyformGrid<org.umamo.runtime.model.WarpLatticeForm>?,
moc3Grid: KeyformGrid<org.umamo.runtime.model.WarpLatticeForm>?,
tolerance: Float,
) {
if (cmo3Grid == null || moc3Grid == null) {
return
}
// Hard-gate the grid shapes like compareMeshKeyforms does: silently skipping unmatched cells
// would let a systematic axis-order or coordinate regression pass this comparison vacuously.
assertEquals(
cmo3Grid.axes.map { axis -> axis.parameterId to axis.keys.toList() },
moc3Grid.axes.map { axis -> axis.parameterId to axis.keys.toList() },
"warp keyform axes above ${drawableId.raw}",
)
val moc3Cells = moc3Grid.cells.associateBy { cell -> cell.coordinate.toList() }
for (cmo3Cell in cmo3Grid.cells) {
val moc3Cell =
moc3Cells[cmo3Cell.coordinate.toList()]
?: error("moc3 warp above ${drawableId.raw} misses cell ${cmo3Cell.coordinate.toList()}")
val cmo3Points = cmo3Cell.form.controlPoints
val moc3Points = moc3Cell.form.controlPoints
assertEquals(cmo3Points.size, moc3Points.size, "warp control-point count above ${drawableId.raw}")
for (coordIndex in cmo3Points.indices) {
assertTrue(
abs(cmo3Points[coordIndex] - moc3Points[coordIndex]) <= tolerance,
"warp control point above ${drawableId.raw}@${cmo3Cell.coordinate.toList()}[$coordIndex]: " +
"cmo3=${cmo3Points[coordIndex]} moc3=${moc3Points[coordIndex]}",
)
}
}
}
/**
* Compares two rotation keyform grids cell by cell and returns the largest total-angle delta seen.
* CMO3 keyform angles are absolute where the moc splits baseAngle + delta, so totals are compared.
*
* @param DrawableId drawableId The drawable whose chain is under comparison (for messages).
* @param Deformer.Rotation cmo3Rotation The CMO3 rotation deformer.
* @param Deformer.Rotation moc3Rotation The MOC3 rotation deformer.
* @param Float tolerance The origin tolerance in the rotation's parent space.
* @return Float The largest absolute total-angle difference in degrees.
*/
private fun compareRotationGrids(
drawableId: DrawableId,
cmo3Rotation: Deformer.Rotation,
moc3Rotation: Deformer.Rotation,
tolerance: Float,
): Float {
val cmo3Grid = cmo3Rotation.geometryGrid ?: return 0f
val moc3Grid = moc3Rotation.geometryGrid ?: return 0f
// Hard-gate the grid shapes like compareMeshKeyforms does: silently skipping unmatched cells
// would report "max angle delta 0.0" for a systematically-wrong conversion.
assertEquals(
cmo3Grid.axes.map { axis -> axis.parameterId to axis.keys.toList() },
moc3Grid.axes.map { axis -> axis.parameterId to axis.keys.toList() },
"rotation keyform axes above ${drawableId.raw}",
)
val moc3Cells = moc3Grid.cells.associateBy { cell -> cell.coordinate.toList() }
var maxAngleDelta = 0f
for (cmo3Cell in cmo3Grid.cells) {
val moc3Cell =
moc3Cells[cmo3Cell.coordinate.toList()]
?: error("moc3 rotation above ${drawableId.raw} misses cell ${cmo3Cell.coordinate.toList()}")
assertTrue(
abs(cmo3Cell.form.originX - moc3Cell.form.originX) <= tolerance &&
abs(cmo3Cell.form.originY - moc3Cell.form.originY) <= tolerance,
"rotation origin above ${drawableId.raw}@${cmo3Cell.coordinate.toList()}: " +
"cmo3=(${cmo3Cell.form.originX}, ${cmo3Cell.form.originY}) " +
"moc3=(${moc3Cell.form.originX}, ${moc3Cell.form.originY})",
)
val cmo3TotalAngle = cmo3Rotation.baseAngle + cmo3Cell.form.angle
val moc3TotalAngle = moc3Rotation.baseAngle + moc3Cell.form.angle
val angleDelta = abs(cmo3TotalAngle - moc3TotalAngle)
if (angleDelta > maxAngleDelta) {
maxAngleDelta = angleDelta
}
assertTrue(
angleDelta <= ANGLE_TOLERANCE_DEGREES,
"rotation angle above ${drawableId.raw}@${cmo3Cell.coordinate.toList()}: " +
"cmo3=$cmo3TotalAngle moc3=$moc3TotalAngle (sign convention?)",
)
assertTrue(abs(cmo3Cell.form.scale - moc3Cell.form.scale) <= 0.001f, "rotation scale above ${drawableId.raw}")
}
// Reflections are FLAG channel tracks now, not pivot-form fields, but the parity claim is the same:
// both import paths must land on the same flip at every cell.
for (flipChannel in listOf(FormChannel.FLIP_X, FormChannel.FLIP_Y)) {
val cmo3Flips = cmo3Rotation.channelGrids[flipChannel]
val moc3Flips = moc3Rotation.channelGrids[flipChannel]
if (cmo3Flips == null || moc3Flips == null) {
continue
}
val moc3FlipCells = moc3Flips.cells.associateBy { cell -> cell.coordinate.toList() }
for (cmo3Cell in cmo3Flips.cells) {
val moc3Cell =
moc3FlipCells[cmo3Cell.coordinate.toList()]
?: error("moc3 rotation above ${drawableId.raw} misses $flipChannel cell ${cmo3Cell.coordinate.toList()}")
assertEquals(cmo3Cell.form, moc3Cell.form, "rotation $flipChannel above ${drawableId.raw}")
}
}
return maxAngleDelta
}
/**
* Compares the render-order leaf sequence: the MOC3 import takes the baked tree verbatim, the CMO3
* import derives it from the org tree; restricted to the shared drawables the two must agree.
*
* @param PuppetModel fromCmo3 The CMO3-imported model.
* @param PuppetModel fromMoc3 The MOC3-imported model.
* @param Set<DrawableId> sharedIds The drawable-id intersection.
*/
private fun compareRenderOrder(fromCmo3: PuppetModel, fromMoc3: PuppetModel, sharedIds: Set<DrawableId>) {
fun leaves(node: RenderNode, into: ArrayList<DrawableId>) {
when (node) {
is RenderDrawable -> into.add(node.id)
is RenderGroup -> node.children.forEach { child -> leaves(child, into) }
}
}
val cmo3Leaves = ArrayList<DrawableId>().also { leaves(fromCmo3.renderRoot, it) }.filter { it in sharedIds }
val moc3Leaves = ArrayList<DrawableId>().also { leaves(fromMoc3.renderRoot, it) }.filter { it in sharedIds }
assertEquals(
cmo3Leaves.map { it.raw },
moc3Leaves.map { it.raw },
"render-order leaf sequence over shared drawables",
)
}
/**
* Whether two float arrays agree element-wise within [tolerance].
*
* @param FloatArray left One array.
* @param FloatArray right The other.
* @param Float tolerance The per-element tolerance.
* @return Boolean True when equal within tolerance.
*/
private fun floatsClose(left: FloatArray, right: FloatArray, tolerance: Float): Boolean {
if (left.size != right.size) {
return false
}
for (valueIndex in left.indices) {
if (abs(left[valueIndex] - right[valueIndex]) > tolerance) {
return false
}
}
return true
}
/**
* A diagnostic suffix for a UV mismatch: reports whether flipping V (v -> 1 - v) would make the
* arrays agree, so a failed assertion names the orientation problem directly.
*
* @param FloatArray cmo3Uvs The CMO3 UVs.
* @param FloatArray moc3Uvs The MOC3 UVs.
* @return String The diagnostic, or an empty string when nothing conclusive can be said.
*/
private fun flipDiagnostic(cmo3Uvs: FloatArray, moc3Uvs: FloatArray): String {
if (cmo3Uvs.size != moc3Uvs.size) {
return " (size mismatch)"
}
val flipped =
FloatArray(moc3Uvs.size) { coordIndex ->
if (coordIndex % 2 == 1) 1f - moc3Uvs[coordIndex] else moc3Uvs[coordIndex]
}
return if (floatsClose(cmo3Uvs, flipped, 0.0005f)) " (moc3 V is flipped: import needs v -> 1 - v)" else ""
}
/**
* Reads the sample's sibling `<basename>.cdi3.json`, or null when absent.
*
* @param File mocFile The `.moc3` sample.
* @return Cdi3Json? The parsed display info, or null.
*/
private fun siblingDisplayInfo(mocFile: File): Cdi3Json? {
// Case-insensitive strip, matching the document loader's basename rule.
val basename = if (mocFile.name.endsWith(".moc3", ignoreCase = true)) mocFile.name.dropLast(".moc3".length) else mocFile.name
val cdi3File = mocFile.parentFile.resolve("$basename.cdi3.json")
if (!cdi3File.isFile) {
return null
}
return Moc3.readCdi3(cdi3File.readText())
}
}
@@ -0,0 +1,74 @@
package org.umamo.render
import org.umamo.format.moc3.Moc3
import org.umamo.interop.moc3.import.Moc3Import
import org.umamo.render.eval.CpuDeformationEvaluator
import java.io.File
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* Default-pose eval sanity over EVERY corpus moc: imports each `.moc3` found beside the
* `-Dmoc3.sample` model and asserts the evaluated world geometry is finite and lands within a
* generous multiple of the canvas. Models with no canvas, and models with no art meshes at all, are
* reported and skipped rather than failed - both are shapes a real `.moc3` takes.
*/
class Moc3EvalSanityTest {
private val sample: File? = System.getProperty("moc3.sample")?.let(::File)?.takeIf { it.isFile }
@Test
fun corpusModelsEvaluateWithinCanvasBounds() {
val corpusRoot = sample?.parentFile?.parentFile?.takeIf { it.isDirectory }
if (corpusRoot == null) {
println("moc3.sample not present; skipping eval sanity test")
return
}
val mocFiles =
corpusRoot.listFiles { candidate -> candidate.isDirectory }.orEmpty()
.flatMap { modelDirectory -> modelDirectory.listFiles { candidate -> candidate.isFile && candidate.extension == "moc3" }.orEmpty().toList() }
.sortedBy { it.path }
assertTrue(mocFiles.isNotEmpty(), "expected corpus .moc3 files under ${corpusRoot.path}")
for (mocFile in mocFiles) {
val mocDocument =
runCatching { Moc3.read(mocFile.readBytes()) }.getOrElse {
println("${mocFile.name}: not decodable, skipping")
continue
}
val model = Moc3Import.fromMocDocument(mocDocument, null)
if (model.canvasWidth <= 0f || model.canvasHeight <= 0f) {
println("${mocFile.name}: no canvas, skipping bounds check")
continue
}
// A moc may legitimately carry no art at all: the offscreen enum-extraction fixtures are parts
// and parameters only, with offscreen flagged on a couple of parts, and the official Cubism
// Core reads drawables=0 for them too. The guard is on the MODEL rather than on the eval
// result so the assertion below stays live - a model that HAS drawables and still evaluates
// to nothing is a regression, not a fixture.
if (model.drawables.isEmpty()) {
println("${mocFile.name}: no drawables, skipping bounds check")
continue
}
val geometry = CpuDeformationEvaluator().evaluate(model, emptyMap())
assertTrue(geometry.worldPositions.isNotEmpty(), "${mocFile.name}: nothing evaluated at the default pose")
// World space is origin-centered: x spans about [-originX, canvasWidth - originX], y the
// negated equivalent. Allow 4x the canvas's larger side in every direction - room for real
// overhang, far below a ppu-scale (1000x+) unit-seam explosion.
val margin = 4f * maxOf(model.canvasWidth, model.canvasHeight)
var checkedValues = 0
for ((drawableId, positions) in geometry.worldPositions) {
for (value in positions) {
assertTrue(value.isFinite(), "${mocFile.name}: non-finite world coordinate on ${drawableId.raw}")
assertTrue(
value > -margin && value < margin,
"${mocFile.name}: world coordinate $value on ${drawableId.raw} is beyond ±$margin - " +
"a coordinate/scale seam regression (see Moc3Import's unit-seam notes)",
)
checkedValues++
}
}
println("${mocFile.name}: ${geometry.worldPositions.size} drawables, $checkedValues coordinates within ±$margin")
}
}
}
@@ -0,0 +1,66 @@
package org.umamo.render
import org.junit.Assume
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.interop.cmo3.cmo3AtlasIngest
import org.umamo.runtime.model.AtlasTileId
import java.io.File
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* The source-artwork display plan on real documents: how many drawables it maps, and how many it
* leaves on the atlas.
*
* The renderer engages the mode only when EVERY layer the plan maps is resident, so a plan that maps
* nothing leaves the whole puppet on its atlas - silently, because that is also what a document with
* no artwork looks like. This is the measurement that tells those two apart.
*/
class SourceLayerPlanCorpusTest {
private fun corpusFiles(): List<File> =
System.getProperty("cmo3.probe")
.orEmpty()
.split(',')
.map { entry -> entry.trim() }
.filter { entry -> entry.isNotEmpty() }
.map(::File)
.filter { file -> file.isFile }
@Test
fun theArtworkPlanMapsCorpusDrawables() {
val files = corpusFiles()
Assume.assumeTrue("no cmo3.probe corpus models", files.isNotEmpty())
var mappedTotal = 0
var decodedTotal = 0
val lines = mutableListOf<String>()
for (file in files) {
val root = Cmo3.read(file).root as? CModelSource ?: continue
val puppet = Cmo3Import.fromModelSource(root).let { model -> model.copy(rendersFromSourceLayers = true) }
if (puppet.atlas.tiles.isEmpty()) {
continue
}
val plan = buildLayerDrawPlan(puppet)
val meshed = puppet.drawables.count { drawable -> drawable.mesh != null }
mappedTotal += plan.drawsByDrawableId.size
// The delivery half, assembled exactly as the document loader does it: the renderer engages
// only when EVERY mapped layer decodes, so a plan that maps everything and decodes nothing
// leaves the whole puppet on its atlas - and looks identical to having no artwork at all.
val model = Cmo3.read(file)
val tileResources = cmo3AtlasIngest(root).imageResourceByTile
val rasters = SourceArtRasters.fromPng { tileId -> tileResources[tileId]?.let(model::extractLayerPng) }
val decoded = plan.layerByteCostByKey.keys.count { key -> rasters.decodeRaster(AtlasTileId(key)) != null }
decodedTotal += decoded
lines.add(
"${file.name}: ${plan.drawsByDrawableId.size}/$meshed mapped, " +
"${plan.unresolvedDrawableCount} unresolved, $decoded/${plan.layerByteCostByKey.size} layers decoded, " +
"pagesAddressed=${puppet.atlas.storedUvsAddressPages}",
)
}
lines.take(40).forEach { line -> println("[plan] $line") }
assertTrue(mappedTotal > 0, "no corpus drawable mapped to artwork; the plan is empty everywhere")
assertTrue(decodedTotal > 0, "no mapped layer decoded; the renderer would never engage the mode")
}
}
@@ -0,0 +1,165 @@
package org.umamo.render.eval
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.moc.MocCodec
import org.umamo.format.moc3.moc.Section
import org.umamo.format.moc3.model.BlendShapeTarget
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.runtime.eval.gridCorners
import java.io.File
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* Determines what the baked MOC3 blend-shape deltas are relative to, by joining Model A's ingested
* mesh bindings against Model A's stored delta rows and testing two hypotheses per non-neutral key:
*
* H_SETUP: stored delta = authoredForm - restMesh (the ingested MeshForm.positionDeltas verbatim)
* H_GRID: stored delta = authoredForm - gridFormInterpolatedAtDefaultPose (the same multilinear
* interpolation the runtime performs, sampled with every parameter at its default)
*
* The hypotheses coincide on drawables whose default-pose grid form equals the rest mesh; only
* records where they differ discriminate. Units: MOC3 deltas are model space; the origin cancels
* in a delta, so the conversion is x/ppu with Y components sign-flipped.
*
* MEASURED VERDICT (Model A, 16 discriminating records): H_SETUP is refuted outright (errors 20-50x
* larger than H_GRID). H_GRID holds to first order, but a residual remains on warp-parented
* meshes whose parent warp carries a morph on the same driving parameter - antisymmetric in the
* key (e.g. ArtMesh80 comp 128: implied reference deviates +-147 px at keys -+10 while the
* authored forms there are equal), consistent with the baker pre-compensating the mesh delta
* through the morphed parent warp. The assert below is therefore DIRECTIONAL (grid beats setup
* on every discriminating record); the posed oracle quantifies the coupling end to end.
*
* Skips gracefully when the Model A corpus pair is absent.
*/
class BlendDeltaFrameProbeTest {
private val modelACmo3: File? =
System.getProperty("cmo3.probe")?.split(',')?.map(::File)
?.firstOrNull { it.isFile && it.name.startsWith("modelA") }
private val modelAMoc3: File? =
System.getProperty("moc3.samples")?.let(::File)?.takeIf { it.isDirectory }
?.walkTopDown()?.firstOrNull { it.isFile && it.name == "modelA.moc3" }
@Test
fun storedMeshDeltasIdentifyTheirReferenceFrame() {
val cmo3File = modelACmo3
val moc3File = modelAMoc3
if (cmo3File == null || moc3File == null) {
println("Model A corpus pair not present; skipping delta-frame probe")
return
}
val root = Cmo3.read(cmo3File).root as? CModelSource ?: error("root is not a CModelSource")
val puppet = Cmo3Import.fromModelSource(root)
val model = MocCodec.read(moc3File.readBytes())
val document = Moc3.decode(model)
val pixelsPerUnit = model.canvasInfo?.pixelsPerUnit ?: error("no canvas info")
val positionValues = model.sections.floatArray(Section.KEYFORM_POSITION_VALUES)
val meshPositionIndex = model.sections.intArray(Section.KEYFORM_POSITION_INDEX)
val defaultByParameter = puppet.parameters.associate { it.id to it.default }
var discriminating = 0
var setupWins = 0
var gridWins = 0
var coinciding = 0
var worstGridError = 0f
for (record in document.blendShapes) {
if (record.target != BlendShapeTarget.ART_MESH) {
continue
}
val meshId = document.artMeshes[record.targetIndex].id
val parameterId = document.parameters[record.parameterIndex].id
val drawable = puppet.drawables.firstOrNull { it.id.raw == meshId } ?: continue
val binding = drawable.blendShapes.firstOrNull { it.parameterId.raw == parameterId } ?: continue
val base = drawable.mesh?.positions ?: continue
// The grid form at the DEFAULT pose, multilinearly interpolated (null when ungridded).
val gridAtDefault =
drawable.geometryGrid?.let { grid ->
gridCorners(grid) { queried -> defaultByParameter[queried] ?: 0f }
?.let { corners -> blendLocalFromCorners(grid, base, corners) }
}
for (keyIndex in binding.keys.indices) {
if (keyIndex == binding.neutralIndex) {
continue
}
val authoredDeltas = (binding.forms[keyIndex])?.positionDeltas ?: continue
val stored = meshPositionIndex[record.recordBase + keyIndex]
var setupError = 0f
var gridError = 0f
var hypothesisGap = 0f
for (componentIndex in authoredDeltas.indices) {
// Canvas -> model: divide by ppu; Y components (odd indices) flip sign.
val sign = if (componentIndex % 2 == 1) -1f else 1f
val setupDelta = sign * authoredDeltas[componentIndex] / pixelsPerUnit
val gridReference =
gridAtDefault?.let { it[componentIndex] - base[componentIndex] } ?: 0f
val gridDelta = sign * (authoredDeltas[componentIndex] - gridReference) / pixelsPerUnit
val storedValue = positionValues[stored + componentIndex]
setupError = maxOf(setupError, abs(storedValue - setupDelta))
gridError = maxOf(gridError, abs(storedValue - gridDelta))
hypothesisGap = maxOf(hypothesisGap, abs(setupDelta - gridDelta))
}
val tolerance = 2e-3f
if (hypothesisGap <= tolerance) {
coinciding++
} else {
discriminating++
worstGridError = maxOf(worstGridError, gridError)
if (setupError < gridError) {
setupWins++
}
if (gridError < setupError) {
gridWins++
}
println(
"[probe] $meshId/$parameterId key=${binding.keys[keyIndex]} " +
"setupErr=$setupError gridErr=$gridError gap=$hypothesisGap",
)
// Diagnostic: the reference frame the FILE implies (authored - stored, canvas
// units) vs the grid-at-default hypothesis, at the worst-residual component.
var worstComponent = 0
var worstResidual = 0f
for (componentIndex in authoredDeltas.indices) {
val sign = if (componentIndex % 2 == 1) -1f else 1f
val impliedReference =
authoredDeltas[componentIndex] - sign * positionValues[stored + componentIndex] * pixelsPerUnit
val gridReference = gridAtDefault?.let { it[componentIndex] - base[componentIndex] } ?: 0f
val residual = abs(impliedReference - gridReference)
if (residual > worstResidual) {
worstResidual = residual
worstComponent = componentIndex
}
}
val sign = if (worstComponent % 2 == 1) -1f else 1f
val impliedReference =
authoredDeltas[worstComponent] - sign * positionValues[stored + worstComponent] * pixelsPerUnit
val gridReference = gridAtDefault?.let { it[worstComponent] - base[worstComponent] } ?: 0f
println(
"[probe] worst comp=$worstComponent (${if (worstComponent % 2 == 0) "x" else "y"}) " +
"authoredDelta=${authoredDeltas[worstComponent]} impliedRef=$impliedReference " +
"gridRef=$gridReference residualPx=$worstResidual",
)
}
}
}
println(
"[probe] E5: discriminating=$discriminating (setup=$setupWins grid=$gridWins) " +
"coinciding=$coinciding worstGridErr=$worstGridError",
)
assertTrue(discriminating + coinciding > 0, "Model A should yield joinable mesh records")
if (discriminating > 0) {
assertTrue(
gridWins == discriminating,
"grid-at-default should beat the setup frame on every discriminating record " +
"(setup=$setupWins grid=$gridWins)",
)
}
}
}
@@ -0,0 +1,166 @@
package org.umamo.render.eval
import org.junit.Assume
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.model.BlendShape
import org.umamo.format.moc3.model.BlendShapeKeyform
import org.umamo.format.moc3.model.Rgb
import org.umamo.interop.moc3.import.Moc3Import
import org.umamo.runtime.model.ParameterId
import java.io.File
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* Posed differential validation of blend-shape CHANNEL deltas, opacity and multiply/screen color.
*
* A blend-shape record carries a delta row per key for every channel its object owns, not only for
* geometry. [BlendShapeOracleTest] compares vertex-position hashes and so cannot see these at all;
* this gate poses the driving parameter at the key that actually carries a non-zero channel delta and
* compares the runtime's exposed per-drawable opacity and colours.
*
* Poses are DERIVED like the deformer-channel gate's: the test reads the format layer for records
* whose keyforms carry a non-zero channel delta and sweeps only those parameters, so a re-authored rig
* keeps being covered and a rig with no channel deltas costs nothing. A record's color delta rows are
* ADDITIVE, so their identity is zero rather than Cubism's (1,1,1) multiply / (0,0,0) screen - a row of
* all zeros contributes nothing and is not worth a pose.
*
* Gated on `relive.dumpModel` + `relive.coreLib` + `moc3.samples`; skips when any is absent.
*/
class BlendShapeChannelOracleTest {
/** Caps the poses per model so a densely-keyed rig cannot turn this into a multi-minute run. */
private val maximumPosesPerModel = 12
/**
* Whether [color] carries any additive contribution (absent or all-zero rows contribute nothing).
*
* @param Rgb? color The delta row.
* @return Boolean True when the row would change the result.
*/
private fun isNonZero(color: Rgb?): Boolean =
color != null && (color.r != 0f || color.g != 0f || color.b != 0f)
/**
* Whether [keyform] carries a non-zero opacity or color delta.
*
* @param BlendShapeKeyform keyform One key's delta payload.
* @return Boolean True when a channel would move.
*/
private fun carriesChannelDelta(keyform: BlendShapeKeyform): Boolean =
when (keyform) {
is BlendShapeKeyform.Mesh ->
keyform.form.opacity != 0f || isNonZero(keyform.form.multiplyColor) || isNonZero(keyform.form.screenColor)
is BlendShapeKeyform.Warp ->
keyform.form.opacity != 0f || isNonZero(keyform.form.multiplyColor) || isNonZero(keyform.form.screenColor)
is BlendShapeKeyform.Rotation ->
keyform.form.opacity != 0f || isNonZero(keyform.form.multiplyColor) || isNonZero(keyform.form.screenColor)
is BlendShapeKeyform.Part -> false
}
/**
* The poses that activate each record carrying a channel delta: its driving parameter set to the
* key position of the key whose row is non-zero, everything else left at its default.
*
* @param MocDocument document The decoded model.
* @return List<Map<String, Float>> One pose per (record, interesting key).
*/
private fun channelDeltaPoses(document: MocDocument): List<Map<String, Float>> {
val poses = LinkedHashSet<Map<String, Float>>()
for (record: BlendShape in document.blendShapes) {
val parameterId = document.parameters.getOrNull(record.parameterIndex)?.id ?: continue
for (keyIndex in record.keyforms.indices) {
if (keyIndex == record.neutralKeyIndex || !carriesChannelDelta(record.keyforms[keyIndex])) {
continue
}
val keyPosition = record.keyPositions.getOrNull(keyIndex) ?: continue
poses.add(mapOf(parameterId to keyPosition))
}
}
return poses.take(maximumPosesPerModel)
}
@Test
fun blendShapeChannelDeltasMatchTheOracle() {
val dumpModel = requireOracleInput("relive.dumpModel")
val coreLib = requireOracleInput("relive.coreLib")
val samples =
System.getProperty("moc3.samples")
?.let(::File)
?.takeIf { it.isDirectory }
?.walkTopDown()
// work/ holds our own bake outputs - same model, different name, no new coverage.
?.filter { it.isFile && it.extension == "moc3" && it.parentFile?.name != "work" }
?.sortedBy { it.name }
?.toList()
.orEmpty()
Assume.assumeTrue("[oracle] absent -Dmoc3.samples", samples.isNotEmpty())
var comparedDrawableStates = 0
var posedModels = 0
val mismatches = ArrayList<String>()
for (mocFile in samples) {
val mocDocument = runCatching { Moc3.read(mocFile.readBytes()) }.getOrNull() ?: continue
val poses = channelDeltaPoses(mocDocument)
if (poses.isEmpty()) {
continue
}
posedModels++
// The canvas-space rebase is the app's real ingest path and the channels compared here are
// rebase-invariant, so running the rebased model keeps the gate on the rendered path.
val puppet = org.umamo.render.restMeshesToCanvasSpace(Moc3Import.fromMocDocument(mocDocument, null))
println("[oracle] ${mocFile.name}: ${poses.size} blend-shape channel-delta poses")
for (pose in poses) {
val dump = runOracleDump(dumpModel, coreLib, mocFile, pose)
val parameterValues = pose.entries.associate { ParameterId(it.key) to it.value }
val inputs = preparePose(puppet, parameterValues)
for (drawableInputs in inputs.drawables) {
val oracleEntry = dump.entries[drawableInputs.drawableId.raw] ?: continue
if (oracleNeverEvaluated(oracleEntry)) {
continue
}
comparedDrawableStates++
val label = "${mocFile.name} pose=$pose ${drawableInputs.drawableId.raw}"
checkChannel(mismatches, label, "op", oracleEntry.opacity, drawableInputs.opacity)
if (oracleEntry.multiplyRgba.size == 4 && oracleEntry.screenRgba.size == 4) {
checkChannel(mismatches, label, "mulR", oracleEntry.multiplyRgba[0], drawableInputs.multiplyColor.red)
checkChannel(mismatches, label, "mulG", oracleEntry.multiplyRgba[1], drawableInputs.multiplyColor.green)
checkChannel(mismatches, label, "mulB", oracleEntry.multiplyRgba[2], drawableInputs.multiplyColor.blue)
checkChannel(mismatches, label, "scrR", oracleEntry.screenRgba[0], drawableInputs.screenColor.red)
checkChannel(mismatches, label, "scrG", oracleEntry.screenRgba[1], drawableInputs.screenColor.green)
checkChannel(mismatches, label, "scrB", oracleEntry.screenRgba[2], drawableInputs.screenColor.blue)
}
}
}
}
// A run that posed nothing would pass while proving nothing, which is the failure mode every
// corpus gate here is prone to. modelC carries non-zero color delta rows, so the corpus reaches this.
assertTrue(posedModels > 0, "no corpus model carried a blend-shape channel delta to pose")
println(
"[oracle] blend-shape channels: $comparedDrawableStates drawable states across $posedModels models, " +
"${mismatches.size} mismatches",
)
assertTrue(
mismatches.isEmpty(),
"blend-shape channel deltas disagree with the oracle:\n" + mismatches.take(20).joinToString("\n"),
)
}
/**
* Records a channel mismatch when ours differs from the oracle beyond tolerance.
*
* @param ArrayList mismatches The shared collector.
* @param String label The model/pose/drawable identifier.
* @param String channel Which channel is being compared.
* @param Float oracle The oracle's value.
* @param Float ours Our evaluated value.
*/
private fun checkChannel(mismatches: ArrayList<String>, label: String, channel: String, oracle: Float, ours: Float) {
if (!oracleCloseEnough(oracle.toDouble(), ours.toDouble())) {
mismatches.add("$label $channel: oracle=$oracle ours=$ours")
}
}
}
@@ -0,0 +1,201 @@
package org.umamo.render.eval
import org.junit.Assume
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.moc3.Moc3
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.interop.moc3.import.Moc3Import
import org.umamo.render.restMeshesToCanvasSpace
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PuppetModel
import java.io.File
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* Posed differential validation of the blend-shape eval against the Umamo C++ runtime: for
* each blend-shape corpus pair (Model A/Model B/Model C), evaluate a matrix of poses that exercise the
* additive pass - at-key, midpoint, beyond-range saturation, combined normal+blend, and the
* min-combined limit curves - and compare per-drawable position hashes against `dump_model`.
*
* Match floors are pinned from the first measured run (the DeformationOracleTest pattern): the
* same nested-warp bounded-ULP residual class shaves a few drawables, plus the mesh-under-
* morphed-warp coupling documented in BlendDeltaFrameProbeTest. Gate against the Umamo C++ Runtime
* only; divergences against the reference implementations are recorded in MOC3.md, never gated
* (reference trust order).
*
* Gated on `relive.dumpModel` + `relive.coreLib` + the corpus pair properties; skips when any is absent.
*/
class BlendShapeOracleTest {
private data class OraclePair(
val name: String,
val cmo3: File,
val moc3: File,
val poses: List<Map<String, Float>>,
/** Minimum matched drawables per pose, pinned from the first measured run. */
val matchFloor: Int,
/** Same floor for the MOC3-imported puppet leg, pinned from its first measured run. */
val moc3ImportMatchFloor: Int,
)
@Test
fun posedBlendShapesMatchOracle() {
val dumpModel = requireOracleInput("relive.dumpModel")
val coreLib = requireOracleInput("relive.coreLib")
val pairs = resolvePairs()
Assume.assumeTrue("[oracle] no blend-shape corpus pairs resolvable", pairs.isNotEmpty())
var totalCompared = 0
var totalMatched = 0
for (pair in pairs) {
val root = Cmo3.read(pair.cmo3).root as? CModelSource ?: error("${pair.name}: root is not a CModelSource")
val puppet = Cmo3Import.fromModelSource(root)
// The MOC3-import leg: the SAME model imported from the baked moc3 itself (the editor's
// document-loader path), so the blend mapping's reference re-addition and space
// conversion are gated end-to-end. Same-file comparison, so any cmo3-vs-moc3
// authoring-state skew is out of the picture by construction.
val moc3Puppet = restMeshesToCanvasSpace(Moc3Import.fromMocDocument(Moc3.read(pair.moc3.readBytes()), null))
for (pose in pair.poses) {
val (compared, matched, worst) = comparePose(puppet, dumpModel, coreLib, pair.moc3, pose)
totalCompared += compared
totalMatched += matched
println("[oracle] ${pair.name} src=cmo3 pose=$pose matched=$matched/$compared worstRelErr=$worst")
// Every blend pose matches at or above its model's DEFAULT-POSE (blend-free) baseline
// Model A 171/198 default vs >= 170 posed (residuals <= 7.7e-5,
// the nested-warp ULP class), Model B 48/59 vs >= 48, Model C 213/260 default vs 215
// posed. Model C's remaining residuals (<= 6.0e-4) are authored-at-default morphs
// applying correctly under the neutral-at-value-0 reading, not the cmo3/moc3
// "authoring-state skew" that a neutral-at-default reading would misattribute them to.
// Regression = any pose below the pinned floor.
assertTrue(
matched >= pair.matchFloor,
"${pair.name} pose=$pose regressed: matched=$matched/$compared (< ${pair.matchFloor})",
)
val (moc3Compared, moc3Matched, moc3Worst) = comparePose(moc3Puppet, dumpModel, coreLib, pair.moc3, pose)
totalCompared += moc3Compared
totalMatched += moc3Matched
println("[oracle] ${pair.name} src=moc3 pose=$pose matched=$moc3Matched/$moc3Compared worstRelErr=$moc3Worst")
assertTrue(
moc3Matched >= pair.moc3ImportMatchFloor,
"${pair.name} src=moc3 pose=$pose regressed: matched=$moc3Matched/$moc3Compared (< ${pair.moc3ImportMatchFloor})",
)
}
}
println("[oracle] blend-shape posed total: $totalMatched/$totalCompared")
assertTrue(totalCompared > 0, "expected comparable drawables")
}
/**
* Evaluates [puppet] at [pose] and compares against the Umamo C++ Runtime's dump of [moc3] at
* the same pose.
*
* @return Triple(compared, matched, worst relative error) for the pose.
*/
private fun comparePose(
puppet: PuppetModel,
dumpModel: File,
coreLib: File,
moc3: File,
pose: Map<String, Float>,
): Triple<Int, Int, Double> {
val geometry =
CpuDeformationEvaluator().evaluate(puppet, pose.mapKeys { ParameterId(it.key) })
val dump = runOracleDump(dumpModel, coreLib, moc3, pose)
var compared = 0
var matched = 0
var worst = 0.0
for (drawable in puppet.drawables) {
val entry = dump.entries[drawable.id.raw] ?: continue
val world = geometry.worldPositions[drawable.id] ?: continue
compared++
// Same transform as the default-pose gate: (x-ox)/ppu, (y+oy)/ppu (umamo pre-flips Y).
val hash = oracleTransformedHash(world, dump.originX, -dump.originY, dump.pixelsPerUnit)
if (oracleCloseEnough(hash, entry.vposH)) {
matched++
} else {
val relativeError = Math.abs(hash - entry.vposH) / maxOf(1.0, Math.abs(entry.vposH))
worst = maxOf(worst, relativeError)
}
}
return Triple(compared, matched, worst)
}
/** The blend-shape corpus pairs with their pose matrices, filtered to what exists locally. */
private fun resolvePairs(): List<OraclePair> {
val cmo3s =
System.getProperty("cmo3.probe")?.split(',')?.map(::File)?.filter { it.isFile }.orEmpty()
val moc3Root = System.getProperty("moc3.samples")?.let(::File)?.takeIf { it.isDirectory }
fun moc3(name: String): File? = moc3Root?.walkTopDown()?.firstOrNull { it.isFile && it.name == name }
fun cmo3(prefix: String): File? = cmo3s.firstOrNull { it.name.startsWith(prefix) }
val pairs = ArrayList<OraclePair>()
val modelA = cmo3("modelA")
val modelAMoc = moc3("modelA.moc3")
if (modelA != null && modelAMoc != null) {
pairs.add(
OraclePair(
"Model A",
modelA,
modelAMoc,
listOf(
// Default pose first: a blend-free baseline separating pre-existing
// residuals (nested-warp ULP class, model-state skew) from blend errors.
emptyMap(),
mapOf("ParamEyeSize" to -1f),
mapOf("ParamEyeSize" to -0.5f),
// Beyond-range: saturates to the end key (confirmed via the Umamo C++ Runtime).
mapOf("ParamEyeSize" to -1.5f),
mapOf("ParamEyeSize" to -1f, "ParamAngleX" to 20f),
// The warp-coupling case documented in BlendDeltaFrameProbeTest.
mapOf("ParamBodyAngleX2" to 10f),
mapOf("ParamBrowLY" to -1f),
),
matchFloor = 170,
moc3ImportMatchFloor = 165,
),
)
}
val modelB = cmo3("modelB")
val modelBMoc = moc3("modelB.moc3")
if (modelB != null && modelBMoc != null) {
pairs.add(
OraclePair(
"Model B",
modelB,
modelBMoc,
listOf(
emptyMap(),
mapOf("ParamA" to 1f, "ParamMouthOpenY" to 1f),
// The limit ramp: contribution scaled to 0.5x / suppressed to zero.
mapOf("ParamA" to 1f, "ParamMouthOpenY" to 0.5f),
mapOf("ParamA" to 1f, "ParamMouthOpenY" to 0f),
),
matchFloor = 48,
moc3ImportMatchFloor = 44,
),
)
}
val modelC = cmo3("modelC")
val modelCMoc = moc3("modelC.moc3")
if (modelC != null && modelCMoc != null) {
pairs.add(
OraclePair(
"Model C",
modelC,
modelCMoc,
listOf(
emptyMap(),
// Min-combination: multiplier = min over the inverse ramps, not the product.
mapOf("ParamA" to 1f, "ParamI" to 0.6f, "ParamU" to 0.8f),
),
matchFloor = 213,
moc3ImportMatchFloor = 212,
),
)
}
return pairs
}
}
@@ -0,0 +1,155 @@
package org.umamo.render.eval
import org.junit.Assume
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.moc.MocCodec
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.interop.moc3.export.Moc3Export
import java.io.File
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* A CMO3 exported to MOC3 EVALUATES like the editor's own bake of the same model.
*
* The end-to-end statement of the whole export: take the source project, lower it ourselves, and let
* the official runtime pose both files. Nothing of ours is in the loop at evaluation time, so a
* disagreement is about the file we wrote, not about our math.
*
* Two tiers, because the two files are not obliged to be byte-alike:
*
* - The exported file must LOAD, and every drawable the bake has must be present and evaluated. That
* is equality, and `runOracleDump`'s non-zero-exit check gates the loading half for free.
* - GEOMETRY is a measured floor, not an equality. The editor's bake is its own derivation from the
* same source, and the two need only agree to within the authoring skew - so the test pins how many
* drawables land within tolerance and fails when that number drops, which is what a lowering
* regression looks like from here.
*
* Gated on `relive.dumpModel` + `relive.coreLib` + `cmo3.probe` + `moc3.samples`.
*/
class Cmo3ToMoc3OracleTest {
/**
* The corpus twins, joined by base name.
*
* @return List Each (base name, cmo3, moc3) triple.
*/
private fun twins(): List<Triple<String, File, File>> {
val cmo3Files =
System.getProperty("cmo3.probe")
?.split(',')
?.map { path -> File(path.trim()) }
?.filter { file -> file.isFile }
?.associateBy { file -> file.nameWithoutExtension }
.orEmpty()
val moc3Files =
System.getProperty("moc3.samples")
?.let(::File)
?.takeIf { directory -> directory.isDirectory }
?.walkTopDown()
?.filter { file -> file.isFile && file.extension == "moc3" && file.parentFile?.name != "work" }
?.associateBy { file -> file.nameWithoutExtension }
.orEmpty()
return cmo3Files.keys
.intersect(moc3Files.keys)
.sorted()
.map { name -> Triple(name, cmo3Files.getValue(name), moc3Files.getValue(name)) }
}
@Test
fun exportedProjectsEvaluateLikeTheEditorsBake() {
val dumpModel = requireOracleInput("relive.dumpModel")
val coreLib = requireOracleInput("relive.coreLib")
val twins = twins()
Assume.assumeTrue("[oracle] no cmo3/moc3 twins", twins.isNotEmpty())
val outputDir = File("build/cmo3-to-moc3").apply { mkdirs() }
val failures = ArrayList<String>()
var comparedModels = 0
var comparedDrawables = 0
var geometryMatches = 0
val perModel = ArrayList<String>()
for ((name, cmo3File, moc3File) in twins) {
val baked = Moc3.decode(MocCodec.read(moc3File.readBytes()))
val root = Cmo3.read(cmo3File).root as? CModelSource ?: continue
val puppet = Cmo3Import.fromModelSource(root)
val (bytes, _) =
runCatching { Moc3Export.write(puppet, baked.version) }.getOrElse { failure ->
failures.add("$name: the CMO3 would not lower to a moc ($failure)")
continue
}
val exportedFile = File(outputDir, "$name.moc3").apply { writeBytes(bytes) }
val bakedDump = runOracleDump(dumpModel, coreLib, moc3File, emptyMap())
val ourDump = runOracleDump(dumpModel, coreLib, exportedFile, emptyMap())
// A twin pair is only an oracle when both files are the same revision of the model; the
// structural gate (Cmo3ToMoc3CrossFormatTest) names the one corpus pair that is not.
val shared = bakedDump.entries.keys.intersect(ourDump.entries.keys)
if (shared.size < bakedDump.entries.size * 9 / 10) {
continue
}
comparedModels++
var modelCompared = 0
var modelMatches = 0
for (drawableId in shared) {
val expected = bakedDump.entries.getValue(drawableId)
val actual = ourDump.entries.getValue(drawableId)
if (oracleNeverEvaluated(expected)) {
continue
}
comparedDrawables++
if (expected.vtx != actual.vtx) {
failures.add("$name $drawableId: ${expected.vtx} vertices in the bake, ${actual.vtx} in ours")
continue
}
// Opacity is a pose result, not a derived coordinate - the two files must agree exactly on
// what the default pose makes this drawable.
if (!oracleCloseEnough(expected.opacity.toDouble(), actual.opacity.toDouble())) {
failures.add("$name $drawableId op: ${expected.opacity} vs ${actual.opacity}")
}
modelCompared++
if (oracleCloseEnough(expected.vposH, actual.vposH)) {
geometryMatches++
modelMatches++
}
}
if (modelCompared > 0 && modelMatches < modelCompared) {
// Printed per model so the residue is legible rather than a single percentage: it sits at
// roughly one drawable in ten across EVERY real model, which is what says it is authoring
// skew and not one model's quirk.
perModel.add("$name $modelMatches/$modelCompared")
}
}
assertTrue(comparedModels > 0, "no twin pair could be compared")
val geometryRatio = if (comparedDrawables == 0) 0.0 else geometryMatches.toDouble() / comparedDrawables
println(
"[cross-oracle] $comparedModels twins, $comparedDrawables drawables compared, " +
"$geometryMatches within the oracle's geometry tolerance " +
"(${(geometryRatio * 100).toInt()}%), ${failures.size} failures" +
(if (perModel.isEmpty()) "" else "; below par: $perModel"),
)
assertTrue(failures.isEmpty(), "exported projects do not evaluate like the bake:\n" + failures.take(15).joinToString("\n"))
assertTrue(
geometryRatio >= GEOMETRY_FLOOR,
"only ${(geometryRatio * 100).toInt()}% of drawables land on the bake's geometry, floor is " +
"${(GEOMETRY_FLOOR * 100).toInt()}% - a lowering regression looks exactly like this",
)
}
private companion object {
/**
* The floor under the share of drawables whose evaluated geometry matches the editor's bake.
*
* A FLOOR rather than 100%: the bake is the editor's own derivation from the same project, so the
* two agree only to within its authoring skew - measured at 89% over 1046 drawables of 21 twins,
* spread evenly across models rather than pooled in one. Raise this when the number improves; a
* drop is a regression in the lowering, which is the only thing that can move it.
*
* For scale: writing the project's own pixels-per-unit instead of a bake scale put this at ZERO,
* and every other gate stayed green through it. That is the class of defect the floor catches.
*/
const val GEOMETRY_FLOOR: Double = 0.85
}
}
@@ -0,0 +1,140 @@
package org.umamo.render.eval
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PuppetModel
import java.io.File
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* The compaction gate that needs NO external oracle: import every corpus model twice - once with the
* post-import channel compaction on, once off - and assert the two evaluate identically over a pose sweep.
*
* This is the cheap check that runs wherever the corpus is present, and it is the one that would actually
* catch a compaction fault: the C-core oracles need `relive.dumpModel`/`relive.coreLib` and shell out to an
* external process per pose, so their sweeps stay capped, while this needs nothing but the corpus and
* compares Umamo against ITSELF across many poses, with the un-compacted import as the reference. A
* dropped key that mattered, or a constant lifted onto the wrong static, shows up here.
*
* The comparison is to a tolerance, and the reason is worth stating: where a track collapses, compaction
* is the MORE accurate side. The reference path evaluates a constant channel as `Σ wᵢ·x` over up to 16
* corners, which lands an ULP off (a corpus draw order of 900 sums to 899.99994); the compacted path reads
* the authored 900 from a field. Asserting equality would therefore be asserting that compaction
* reproduces the old arithmetic's noise, which is backwards.
*
* The tolerance is set far below any granularity that could change behaviour - draw order only orders
* drawables a whole unit apart, and opacity is displayed to two decimals - so it admits the ULP while
* still failing on a dropped key that mattered or a constant lifted onto the wrong static.
*/
class CompactionEvalEquivalenceTest {
private companion object {
/** Poses swept per parameter, as fractions across its min..max range. */
val SWEEP_FRACTIONS = listOf(0f, 0.25f, 0.5f, 0.75f, 1f)
/** Geometry is never compacted, so it should be bit-identical; this absorbs nothing in practice. */
const val GEOMETRY_TOLERANCE = 1e-6f
/** Admits the constant-fold ULP (see the class note) while failing on any real channel change. */
const val SCALAR_TOLERANCE = 1e-3f
}
private fun probeFiles(): List<File> =
System.getProperty("cmo3.probe")
?.split(',')
?.map(::File)
?.filter { it.isFile }
?: emptyList()
private fun importCmo3(file: File, compactChannels: Boolean): PuppetModel {
val root = Cmo3.read(file).root as? CModelSource ?: error("${file.name}: root is not a CModelSource")
return Cmo3Import.fromModelSource(root, compactChannels = compactChannels)
}
/**
* Poses that sweep each parameter across its range one at a time, plus the all-default pose.
*
* One parameter at a time rather than a combinatorial sweep: the grids are multilinear, so a fault on
* one axis shows up while the others sit at their defaults, and the corpus models carry enough
* parameters that a product sweep would not finish.
*/
private fun sweepPoses(model: PuppetModel): List<Map<ParameterId, Float>> {
val defaults = model.parameters.associate { parameter -> parameter.id to parameter.default }
val poses = mutableListOf(defaults)
for (parameter in model.parameters) {
for (fraction in SWEEP_FRACTIONS) {
poses.add(defaults + (parameter.id to (parameter.min + (parameter.max - parameter.min) * fraction)))
}
}
return poses
}
@Test
fun compactionDoesNotChangeEvaluation() {
val files = probeFiles()
if (files.isEmpty()) {
println("cmo3.probe not present; skipping compaction equivalence")
return
}
val evaluator = CpuDeformationEvaluator()
var comparedPoses = 0
var totalTracksBefore = 0
var totalTracksAfter = 0
for (file in files) {
val reference = importCmo3(file, compactChannels = false)
val compacted = importCmo3(file, compactChannels = true)
totalTracksBefore += reference.channelTrackCount()
totalTracksAfter += compacted.channelTrackCount()
for (pose in sweepPoses(reference)) {
val referenceGeometry = evaluator.evaluate(reference, pose)
val compactedGeometry = evaluator.evaluate(compacted, pose)
assertEquals(
referenceGeometry.worldPositions.keys,
compactedGeometry.worldPositions.keys,
"${file.name}: the same drawables must be visible",
)
for ((drawableId, referencePositions) in referenceGeometry.worldPositions) {
val compactedPositions = compactedGeometry.worldPositions.getValue(drawableId)
assertEquals(referencePositions.size, compactedPositions.size, "${file.name}: ${drawableId.raw} vertex count")
for (coordIndex in referencePositions.indices) {
assertTrue(
abs(referencePositions[coordIndex] - compactedPositions[coordIndex]) <= GEOMETRY_TOLERANCE,
"${file.name}: ${drawableId.raw}[$coordIndex] geometry moved under compaction",
)
}
val referenceDrawOrder = referenceGeometry.drawOrder.getValue(drawableId)
val compactedDrawOrder = compactedGeometry.drawOrder.getValue(drawableId)
assertTrue(
abs(referenceDrawOrder - compactedDrawOrder) <= SCALAR_TOLERANCE,
"${file.name}: ${drawableId.raw} draw order $referenceDrawOrder -> $compactedDrawOrder",
)
val referenceOpacity = referenceGeometry.opacity.getValue(drawableId)
val compactedOpacity = compactedGeometry.opacity.getValue(drawableId)
assertTrue(
abs(referenceOpacity - compactedOpacity) <= SCALAR_TOLERANCE,
"${file.name}: ${drawableId.raw} opacity $referenceOpacity -> $compactedOpacity",
)
}
comparedPoses++
}
}
println("[Umamo][compaction] $comparedPoses poses over ${files.size} models; channel tracks $totalTracksBefore -> $totalTracksAfter")
assertTrue(comparedPoses > 0, "compared at least one pose")
assertTrue(
totalTracksAfter <= totalTracksBefore,
"compaction must never ADD tracks (before=$totalTracksBefore after=$totalTracksAfter)",
)
}
/** Every channel track carried by every owner in the model - the thing compaction is meant to shrink. */
private fun PuppetModel.channelTrackCount(): Int =
drawables.sumOf { it.channelGrids.gridsByChannel.size } +
deformers.sumOf { it.channelGrids.gridsByChannel.size } +
parts.sumOf { it.channelGrids.gridsByChannel.size } +
glues.sumOf { it.channelGrids.gridsByChannel.size }
}
@@ -0,0 +1,131 @@
package org.umamo.render.eval
import org.junit.Assume
import org.umamo.format.moc3.Moc3
import org.umamo.interop.moc3.import.Moc3Import
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.ParameterId
import java.io.File
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
/**
* Posed differential validation of the offscreen channel eval against the Umamo C++ runtime: for
* each offscreen corpus model, evaluate poses that exercise the keyformed composite channels
* (opacity at-key, midpoint, and the arm draw-order crossfades; authored multiply/screen colors)
* and compare [PoseDeformInputs.partCompositeStates] against `dump_model`'s per-update
* interpolated offscreen arrays (`O` lines - probed pose-DYNAMIC: the oracle re-evaluates them
* each csmUpdateModel). The oracle's colors are RGBA with alpha pinned 1.0 (the runtime model
* carries RGB only); the mask joins are compared statically.
*
* Gated on `relive.dumpModel` + `relive.coreLib` + `moc3.samples`; skips when any is absent.
*/
class CompositeOracleTest {
private data class CompositeCase(val fileName: String, val poses: List<Map<String, Float>>)
private val cases =
listOf(
// Model A: 24 organic offscreens - the Overall hologram fade (1.0 -> 0.85) and the arm
// draw-order opacity crossfades, at keys and midpoints.
CompositeCase(
"modelA.moc3",
listOf(
emptyMap(),
mapOf("ParamHologram" to 1f),
mapOf("ParamHologram" to 0.5f),
mapOf("ParamHandRDrawOrder" to 1f),
mapOf("ParamHandRDrawOrder" to 0.5f, "ParamHandLDrawOrder" to 0.5f),
),
),
// The authored non-identity multiply/screen colors (#677CD1 / #95C068).
CompositeCase("MultiplyScreenColors.moc3", listOf(emptyMap())),
// Offscreen clip list (part expanded to drawables) + invert flag carrier.
CompositeCase("ModelWithOffscreenPartClipping.moc3", listOf(emptyMap())),
)
@Test
fun compositeChannelsMatchOracle() {
val dumpModel = requireOracleInput("relive.dumpModel")
val coreLib = requireOracleInput("relive.coreLib")
val samplesByName =
System.getProperty("moc3.samples")
?.let(::File)
?.takeIf { it.isDirectory }
?.walkTopDown()
?.filter { it.isFile && it.extension == "moc3" }
?.associateBy { it.name }
?: emptyMap()
Assume.assumeTrue("[oracle] absent -Dmoc3.samples", samplesByName.isNotEmpty())
var comparedOffscreens = 0
val mismatches = ArrayList<String>()
for (compositeCase in cases) {
val mocFile = samplesByName[compositeCase.fileName]
if (mocFile == null) {
println("[oracle] ${compositeCase.fileName} not in corpus; skipping")
continue
}
val mocDocument = Moc3.read(mocFile.readBytes())
val puppet = Moc3Import.fromMocDocument(mocDocument, null)
// Part/drawable FILE order (oracle indices) - puppet.parts preserves it, puppet.drawables
// does not (panel reorder), so drawable joins go through the decoded artMesh list.
val drawableIdByFileIndex = mocDocument.artMeshes.map { DrawableId(it.id) }
val knownParameters = puppet.parameters.mapTo(HashSet()) { it.id.raw }
for (pose in compositeCase.poses) {
if (!pose.keys.all { it in knownParameters }) {
println("[oracle] ${compositeCase.fileName} pose=$pose names an unknown parameter; skipping")
continue
}
val dump = runOracleDump(dumpModel, coreLib, mocFile, pose)
assertEquals(
puppet.parts.count { it.activeComposite != null },
dump.offscreens.size,
"${compositeCase.fileName}: offscreen count",
)
val inputs = preparePose(puppet, pose.entries.associate { ParameterId(it.key) to it.value })
for (oracleOffscreen in dump.offscreens) {
val part = puppet.parts[oracleOffscreen.ownerPartIndex]
val composite = assertNotNull(part.activeComposite, "${compositeCase.fileName}: ${part.id.raw} owns an offscreen")
val state =
assertNotNull(
inputs.partCompositeStates[part.id],
"${compositeCase.fileName}: ${part.id.raw} carries a pose state",
)
comparedOffscreens++
val label = "${compositeCase.fileName} pose=$pose ${part.id.raw}"
// The dynamic channels: opacity + multiply/screen RGB at the oracle tolerance.
checkChannel(mismatches, label, "op", oracleOffscreen.opacity, state.opacity)
checkChannel(mismatches, label, "mulR", oracleOffscreen.multiplyRgba[0], state.multiplyColor.red)
checkChannel(mismatches, label, "mulG", oracleOffscreen.multiplyRgba[1], state.multiplyColor.green)
checkChannel(mismatches, label, "mulB", oracleOffscreen.multiplyRgba[2], state.multiplyColor.blue)
checkChannel(mismatches, label, "scrR", oracleOffscreen.screenRgba[0], state.screenColor.red)
checkChannel(mismatches, label, "scrG", oracleOffscreen.screenRgba[1], state.screenColor.green)
checkChannel(mismatches, label, "scrB", oracleOffscreen.screenRgba[2], state.screenColor.blue)
// The RGB-only runtime model rests on alpha staying 1.0 - pin the assumption.
assertEquals(1f, oracleOffscreen.multiplyRgba[3], "$label multiply alpha")
assertEquals(1f, oracleOffscreen.screenRgba[3], "$label screen alpha")
// Static joins: the offscreen mask list resolves to the same drawables.
val oracleMaskIds = oracleOffscreen.maskIndices.mapNotNull { drawableIdByFileIndex.getOrNull(it) }.toSet()
assertEquals(oracleMaskIds, composite.maskedBy.toSet(), "$label mask list")
}
println("[oracle] ${compositeCase.fileName} pose=$pose offscreens=${dump.offscreens.size} OK")
}
}
Assume.assumeTrue("[oracle] no offscreen corpus models resolvable", comparedOffscreens > 0)
// The channels are plain multilinear blends of stored floats on both sides - exact within
// 1e-5, no pinned floor needed; any mismatch is a real regression.
assertTrue(
mismatches.isEmpty(),
"offscreen channel mismatches (${mismatches.size}):\n" + mismatches.joinToString("\n"),
)
println("[oracle] compared $comparedOffscreens offscreen states, all within tolerance")
}
private fun checkChannel(mismatches: ArrayList<String>, label: String, channel: String, oracle: Float, ours: Float) {
if (!oracleCloseEnough(oracle.toDouble(), ours.toDouble())) {
mismatches.add("$label $channel: oracle=$oracle ours=$ours")
}
}
}
@@ -0,0 +1,187 @@
package org.umamo.render.eval
import org.junit.Assume
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
import java.io.File
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* Differential validation against the Umamo C++ Runtime oracle: read a `.cmo3` -> PuppetModel,
* evaluate the default pose, and compare per-drawable hashes against
* `dump_model libcore_re.so model.moc3 --update`.
*
* The oracle prints a rolling hash `hp = hp*1.0000001 + coord` over each drawable's interleaved
* positions (`vpos_h`); umamo's output is transformed to model space and re-hashed, matched by id.
*
* Result: 156/174 match to tiny-ULP (157 before the harness rebuild - see the assertion
* note); the other 18 are sub-pixel residuals (<0.6 px/vertex)
* concentrated in deeply-nested warp chains. Ruled out as causes: FMA contraction, rotation sin/cos,
* vertex extrapolation, blend-at-default - and `warpExtrap` was audited bit-for-bit against the oracle.
* The residual grows with nesting depth, which is most consistent with CMO3↔MOC3 source-data
* re-quantization amplified through the chain (umamo evaluates the CMO3, the oracle the exported MOC3),
* i.e. a serialization difference, not a math error. Well within the bounded-ULP fidelity contract.
*
* Gated on the cmo3/moc3 samples + the Umamo C++ Runtime oracle paths (system properties); skips when absent.
*/
class DeformationOracleTest {
private data class OracleEntry(val vtx: Int, val vposH: Double, val vuvH: Double)
@Test
fun defaultPoseMatchesOracle() {
val cmo3 = requireOracleInput("cmo3.sample")
val moc3 = requireOracleInput("moc3.sample")
val dumpModel = requireOracleInput("relive.dumpModel")
val coreLib = requireOracleInput("relive.coreLib")
val root = Cmo3.read(cmo3).root as? CModelSource ?: error("root is not a CModelSource")
val model = Cmo3Import.fromModelSource(root)
val geometry = CpuDeformationEvaluator().evaluate(model, emptyMap())
val oracle = runOracle(dumpModel, coreLib, moc3)
println("[oracle] umamo drawables=${model.drawables.size} evaluated=${geometry.worldPositions.size} oracle=${oracle.size}")
// Confirmed transform: CMO3 canvas/pixel space -> MOC3 normalized model space = (x-ox)/ppu,
// (y+oy)/ppu (origin = canvas center, ppu from the dump header; umamo already applied -Y).
val ppu = 4500f
val originX = 2250f
val originY = 3250f
val deformerById = model.deformers.associateBy { it.id }
var posMatch = 0
var compared = 0
val mismatches = StringBuilder()
var shown = 0
for (drawable in model.drawables) {
val entry = oracle[drawable.id.raw] ?: continue
val world = geometry.worldPositions[drawable.id] ?: continue
compared++
val hash = transformedHash(world, originX, -originY, ppu, 1f)
if (closeEnough(hash, entry.vposH)) {
posMatch++
} else if (shown < 20) {
val parentId = drawable.parentDeformerId
val relativeError = abs(hash - entry.vposH) / maxOf(1.0, abs(entry.vposH))
val rotationAncestor = hasRotationAncestor(deformerById, parentId)
mismatches.append(
" ${drawable.id.raw}: parent=${parentId?.raw} vtx=${entry.vtx} relErr=${
"%.3g".format(
relativeError,
)
} rotAncestor=$rotationAncestor\n",
)
shown++
}
}
println("[oracle] posMatch=$posMatch / $compared (transform (x-ox)/ppu,(y+oy)/ppu)")
println("[oracle] mismatches (bounded-ULP residuals):\n$mismatches")
// The gate is pinned to 156, not 157: after the oracle harness was rebuilt from csrc (the
// original prebuilt dump_model had no source), all three core builds (fresh -O2, pristine
// _o3, pristine _avx2) reproduce 156 - ArtMesh142 sits at relErr 1.11e-5 against the 1e-5
// closeEnough knife edge, in the same nested-warp residual class as the other 17. This is
// harness FP drift on a borderline drawable, not an umamo eval change, so the gate is
// pinned to the reproducible baseline.
assertTrue(posMatch >= 156, "geometry regressed: posMatch=$posMatch (<156) — investigate before relaxing")
}
/**
* The file [property] points at, skipping the test when it is absent.
*
* A JUnit assumption rather than an early return, so an un-runnable oracle reports SKIPPED instead of
* passing green having compared nothing. This one needs the Umamo C++ Runtime as an external oracle,
* so unlike the corpus gates it cannot be defaulted - it stays opt-in by nature.
*
* @param String property The system property naming the input.
* @return File The existing file.
*/
private fun requireOracleInput(property: String): File {
val file = sysFile(property)
Assume.assumeTrue(
"[oracle] absent -D$property (needs -Dcmo3.sample -Dmoc3.sample -Drelive.dumpModel -Drelive.coreLib)",
file != null,
)
return file!!
}
private fun sysFile(property: String): File? = System.getProperty(property)?.let(::File)?.takeIf { it.exists() }
private fun rollingHash(values: FloatArray): Double {
var hp = 0.0
for (value in values) {
hp = hp * 1.0000001 + value
}
return hp
}
private fun closeEnough(a: Double, b: Double): Boolean {
val scale = maxOf(1.0, abs(a), abs(b))
return abs(a - b) <= 1e-5 * scale
}
private fun transformedHash(world: FloatArray, offsetX: Float, offsetY: Float, scale: Float, signY: Float): Double {
var hp = 0.0
var index = 0
while (index < world.size) {
hp = hp * 1.0000001 + (world[index] - offsetX) / scale
hp = hp * 1.0000001 + signY * (world[index + 1] - offsetY) / scale
index += 2
}
return hp
}
private fun printRange(id: String, world: FloatArray) {
var minX = Float.MAX_VALUE
var maxX = -Float.MAX_VALUE
var minY = Float.MAX_VALUE
var maxY = -Float.MAX_VALUE
var index = 0
while (index < world.size) {
minX = minOf(minX, world[index])
maxX = maxOf(maxX, world[index])
minY = minOf(minY, world[index + 1])
maxY = maxOf(maxY, world[index + 1])
index += 2
}
println("[oracle] $id raw range x[$minX..$maxX] y[$minY..$maxY] first=${world.take(4).toList()}")
}
private fun hasRotationAncestor(deformerById: Map<DeformerId, Deformer>, start: DeformerId?): Boolean {
var current = start
var guard = 0
while (current != null && guard < 10000) {
val deformer = deformerById[current] ?: return false
if (deformer is Deformer.Rotation) {
return true
}
current = deformer.parent
guard++
}
return false
}
private fun runOracle(dumpModel: File, coreLib: File, moc3: File): Map<String, OracleEntry> {
val command = listOf(dumpModel.absolutePath, coreLib.absolutePath, moc3.absolutePath, "--update")
val process = ProcessBuilder(command).redirectErrorStream(true).start()
val output = process.inputStream.bufferedReader().readText()
process.waitFor()
val idRegex = Regex("""id=(\S+)""")
val vtxRegex = Regex("""vtx=(\d+)""")
val vposRegex = Regex("""vpos_h=(\S+)""")
val vuvRegex = Regex("""vuv_h=(\S+)""")
val result = HashMap<String, OracleEntry>()
for (line in output.lineSequence()) {
if (!line.startsWith("D ")) {
continue
}
val id = idRegex.find(line)?.groupValues?.get(1) ?: continue
val vtx = vtxRegex.find(line)?.groupValues?.get(1)?.toIntOrNull() ?: continue
val vposH = vposRegex.find(line)?.groupValues?.get(1)?.toDoubleOrNull() ?: continue
val vuvH = vuvRegex.find(line)?.groupValues?.get(1)?.toDoubleOrNull() ?: continue
result[id] = OracleEntry(vtx, vposH, vuvH)
}
return result
}
}
@@ -0,0 +1,230 @@
package org.umamo.render.eval
import org.junit.Assume
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.model.Deformer
import org.umamo.format.moc3.model.RotationDeformer
import org.umamo.format.moc3.model.WarpDeformer
import org.umamo.interop.moc3.import.Moc3Import
import org.umamo.runtime.model.ParameterId
import java.io.File
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* Posed differential validation of the DEFORMER channel cascade against the Umamo C++ runtime.
*
* A warp or rotation deformer carries its own opacity and multiply/screen color per keyform, and
* the runtime folds those down the deformer chain into every drawable underneath before exposing
* `csmGetDrawableOpacities` / `...MultiplyColors` / `...ScreenColors`. This gate compares that
* exposed per-drawable result against [preparePose]'s, so it covers the whole chain: the drawable's
* own keyform channels and the deformer cascade between them.
*
* Poses are DERIVED, not hand-written: for each model the test reads the format layer to find which
* deformers actually author a non-identity channel, walks those deformers' keyform bindings to the
* parameters that drive them, and sweeps each such parameter across its own key positions plus the
* midpoints between them. Hand-picked poses would silently stop exercising a model whose rig was
* re-authored; derived ones follow it.
*
* The format layer is also why the interesting-deformer search reads [MocDocument] rather than the
* imported [org.umamo.runtime.model.PuppetModel]: searching through the app's own import would only
* prove the cascade agrees with itself, while reading the moc3 source of truth directly keeps the
* gate honest against an independent read of which deformers actually author a channel.
*
* Gated on `relive.dumpModel` + `relive.coreLib` + `moc3.samples`; skips when any is absent.
*/
class DeformerChannelOracleTest {
/** Cubism identity: fully opaque, white multiply, black screen. */
private val opaque = 1f
private val multiplyIdentity = Triple(1f, 1f, 1f)
private val screenIdentity = Triple(0f, 0f, 0f)
/** How many midpoints to insert between consecutive key positions on a swept axis. */
private val midpointsPerSegment = 1
/** Caps the poses per model so a densely-keyed rig cannot turn this into a multi-minute run. */
private val maximumPosesPerModel = 24
@Test
fun deformerChannelsCascadeToDrawablesLikeTheOracle() {
val dumpModel = requireOracleInput("relive.dumpModel")
val coreLib = requireOracleInput("relive.coreLib")
val samples =
System.getProperty("moc3.samples")
?.let(::File)
?.takeIf { it.isDirectory }
?.walkTopDown()
// work/ holds our own bake outputs - same model, different name, no new coverage.
?.filter { it.isFile && it.extension == "moc3" && "work" !in it.path.split(File.separatorChar) }
?.sortedBy { it.name }
?.toList()
.orEmpty()
Assume.assumeTrue("[oracle] absent -Dmoc3.samples", samples.isNotEmpty())
var comparedModels = 0
var comparedDrawableStates = 0
var skippedNeverEvaluated = 0
val mismatches = ArrayList<String>()
for (mocFile in samples) {
val mocDocument = runCatching { Moc3.read(mocFile.readBytes()) }.getOrNull() ?: continue
val drivingParameters = parametersDrivingChannelledDeformers(mocDocument)
if (drivingParameters.isEmpty()) {
continue
}
// The canvas-space rebase is part of the app's real ingest path, and it must preserve every
// non-positional keyform channel (the modelA hologram tint regression: the rebase rebuilt
// MeshForms and silently dropped multiply/screen colours). The channels this gate compares
// are rebase-invariant, so running the rebased model keeps the gate on the rendered path.
val puppet = org.umamo.render.restMeshesToCanvasSpace(Moc3Import.fromMocDocument(mocDocument, null))
val poses = derivePoses(mocDocument, drivingParameters)
comparedModels++
println("[oracle] ${mocFile.name}: ${drivingParameters.size} channelled-deformer parameters, ${poses.size} poses")
for (pose in poses) {
val dump = runOracleDump(dumpModel, coreLib, mocFile, pose)
val parameterValues = pose.entries.associate { ParameterId(it.key) to it.value }
val inputs = preparePose(puppet, parameterValues)
for (drawableInputs in inputs.drawables) {
val oracleEntry = dump.entries[drawableInputs.drawableId.raw] ?: continue
/*
* The runtime core FREEZES an art mesh whose own keyform binding - or any ancestor
* deformer's - is out of its keyed parameter range, skipping it entirely during the
* update, so every computed field stays at the zero it was allocated with. Umamo
* instead evaluates such a drawable live, and that difference spans geometry as well
* as these channels (the oracle reports `vpos_h=0` for them), so it is a separate gap
* from the channel cascade this test gates - see TODO § Puppet Model, CMO3, MOC3.
* Excluded here so this gate keeps measuring one thing.
*/
if (oracleNeverEvaluated(oracleEntry)) {
skippedNeverEvaluated++
continue
}
comparedDrawableStates++
val label = "${mocFile.name} pose=$pose ${drawableInputs.drawableId.raw}"
checkChannel(mismatches, label, "op", oracleEntry.opacity, drawableInputs.opacity)
if (oracleEntry.multiplyRgba.size == 4 && oracleEntry.screenRgba.size == 4) {
checkChannel(mismatches, label, "mulR", oracleEntry.multiplyRgba[0], drawableInputs.multiplyColor.red)
checkChannel(mismatches, label, "mulG", oracleEntry.multiplyRgba[1], drawableInputs.multiplyColor.green)
checkChannel(mismatches, label, "mulB", oracleEntry.multiplyRgba[2], drawableInputs.multiplyColor.blue)
checkChannel(mismatches, label, "scrR", oracleEntry.screenRgba[0], drawableInputs.screenColor.red)
checkChannel(mismatches, label, "scrG", oracleEntry.screenRgba[1], drawableInputs.screenColor.green)
checkChannel(mismatches, label, "scrB", oracleEntry.screenRgba[2], drawableInputs.screenColor.blue)
}
}
}
}
Assume.assumeTrue("[oracle] no corpus model authors a deformer channel", comparedModels > 0)
assertTrue(
mismatches.isEmpty(),
"deformer-channel cascade mismatches (${mismatches.size} of $comparedDrawableStates drawable states):\n" +
mismatches.take(40).joinToString("\n") +
if (mismatches.size > 40) "\n… and ${mismatches.size - 40} more" else "",
)
println(
"[oracle] compared $comparedDrawableStates drawable channel states across $comparedModels models, " +
"all within tolerance ($skippedNeverEvaluated skipped as never-evaluated by the oracle)",
)
}
/**
* Finds the parameters driving any deformer that authors a non-identity opacity or color.
*
* @param MocDocument mocDocument The decoded model.
* @return Map<String, FloatArray> Parameter id → the key positions of the axes that drive one.
*/
private fun parametersDrivingChannelledDeformers(mocDocument: MocDocument): Map<String, FloatArray> {
val driving = LinkedHashMap<String, FloatArray>()
for (deformer in mocDocument.deformers) {
if (!authorsAChannel(deformer)) {
continue
}
val binding = mocDocument.keyformBinding(deformer.keyformBindingIndex) ?: continue
for (axis in binding.axes) {
val parameter = mocDocument.parameters.getOrNull(axis.parameterIndex) ?: continue
// Union the key positions when several channelled deformers share a parameter, so a
// sweep visits every key any of them is authored at.
val existing = driving[parameter.id]
driving[parameter.id] =
if (existing == null) {
axis.keyPositions.copyOf()
} else {
(existing.toSortedSet() + axis.keyPositions.toSortedSet()).toFloatArray()
}
}
}
return driving
}
/**
* Whether any of this deformer's keyforms departs from the identity channels.
*
* @param Deformer deformer The warp or rotation deformer.
* @return Boolean True when it authors an opacity or color worth sweeping.
*/
private fun authorsAChannel(deformer: Deformer): Boolean {
val channels =
when (deformer) {
is WarpDeformer -> deformer.keyforms.map { Triple(it.opacity, it.multiplyColor, it.screenColor) }
is RotationDeformer -> deformer.keyforms.map { Triple(it.opacity, it.multiplyColor, it.screenColor) }
}
return channels.any { (opacity, multiplyColor, screenColor) ->
opacity != opaque ||
(multiplyColor != null && Triple(multiplyColor.r, multiplyColor.g, multiplyColor.b) != multiplyIdentity) ||
(screenColor != null && Triple(screenColor.r, screenColor.g, screenColor.b) != screenIdentity)
}
}
/**
* Builds the pose sweep: the default pose, then each driving parameter visited alone at each of
* its key positions and at the midpoints between them.
*
* One parameter moves at a time on purpose. A combined sweep would multiply out to thousands of
* dumps, and a mismatch in one would not say which axis caused it.
*
* @param MocDocument mocDocument The decoded model (for parameter defaults).
* @param Map drivingParameters Parameter id → key positions to visit.
* @return List<Map<String, Float>> The poses to evaluate, default pose first.
*/
private fun derivePoses(mocDocument: MocDocument, drivingParameters: Map<String, FloatArray>): List<Map<String, Float>> {
val poses = ArrayList<Map<String, Float>>()
poses.add(emptyMap())
for ((parameterId, keyPositions) in drivingParameters) {
val parameter = mocDocument.parameters.firstOrNull { it.id == parameterId } ?: continue
val sorted = keyPositions.distinct().sorted()
val visits = ArrayList<Float>(sorted)
for (keyIndex in 0 until sorted.size - 1) {
val low = sorted[keyIndex]
val high = sorted[keyIndex + 1]
for (step in 1..midpointsPerSegment) {
visits.add(low + (high - low) * step / (midpointsPerSegment + 1f))
}
}
// Clamp to the parameter's DECLARED range. A keyform axis can carry key positions outside
// it (nothing in the format forbids a rig keeping keys from a since-narrowed range), and
// the runtime core clamps the written value to [min, max] before evaluating. Sweeping an
// out-of-range value would compare our extrapolation against the core's clamp - a real
// difference, but a different one from the channel cascade this test gates.
for (value in visits.map { it.coerceIn(parameter.minimumValue, parameter.maximumValue) }.distinct().sorted()) {
// Skip the default - the empty pose already covers it, and repeating it wastes a dump.
if (value == parameter.defaultValue) {
continue
}
poses.add(mapOf(parameterId to value))
if (poses.size >= maximumPosesPerModel) {
println("[oracle] pose sweep capped at $maximumPosesPerModel; later parameters not visited")
return poses
}
}
}
return poses
}
private fun checkChannel(mismatches: ArrayList<String>, label: String, channel: String, oracle: Float, ours: Float) {
if (!oracleCloseEnough(oracle.toDouble(), ours.toDouble())) {
mismatches.add("$label $channel: oracle=$oracle ours=$ours")
}
}
}
@@ -0,0 +1,48 @@
package org.umamo.render.eval
import org.junit.Assume
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.runtime.model.ParameterId
import java.io.File
import kotlin.math.hypot
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* Corpus E2E for glue: on a real model at a non-default tail pose, every glued seam pair must weld to
* essentially one point (the editor's weights satisfy `wA + wB ≈ 1`, so `A'` and `B'` converge). This is
* the real-model counterpart of the synthetic `GlueTest`; without the glue pass the tail strips split by
* hundreds of pixels. Gated on `-Dcmo3.sample`; self-skips without it.
*/
class GlueCorpusTest {
@Test
fun glueWeldsSeamPairsOnCorpus() {
val file = File(System.getProperty("cmo3.sample") ?: "")
Assume.assumeTrue("[glue-e2e] no cmo3.sample corpus model", file.isFile)
val root = Cmo3.read(file).root as? CModelSource ?: return
val puppet = Cmo3Import.fromModelSource(root)
assertTrue(puppet.glues.isNotEmpty(), "corpus model should carry glue affecters")
val geometry = CpuDeformationEvaluator().evaluate(puppet, mapOf(ParameterId("Param_Angle_Rotation3") to 43.31f))
var maxGap = 0.0
var weldedPairs = 0
for (glue in puppet.glues) {
val vertsA = geometry.worldPositions[glue.meshA] ?: continue
val vertsB = geometry.worldPositions[glue.meshB] ?: continue
for (pair in glue.pairs) {
val gap =
hypot(
(vertsA[pair.indexA * 2] - vertsB[pair.indexB * 2]).toDouble(),
(vertsA[pair.indexA * 2 + 1] - vertsB[pair.indexB * 2 + 1]).toDouble(),
)
maxGap = maxOf(maxGap, gap)
weldedPairs++
}
}
println("[glue-e2e] welded pairs=$weldedPairs maxGap=${"%.4f".format(maxGap)}px")
assertTrue(weldedPairs > 0, "should have welded at least one pair")
assertTrue(maxGap < 1.0, "glued seam pairs should weld to ~one point, but maxGap=$maxGap px")
}
}
@@ -0,0 +1,154 @@
package org.umamo.render.eval
import org.junit.Assume
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.moc.MocCodec
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.interop.ExportNotice
import org.umamo.interop.moc3.export.Moc3Export
import org.umamo.interop.moc3.import.Moc3Import
import org.umamo.runtime.model.RuntimeFeature
import java.io.File
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* Every corpus model exports at every version BELOW its own, and each of those files loads and
* evaluates in the official core.
*
* A downgrade cannot be checked by comparing against the source - the whole point is that features
* are gone - so this asserts the two things that must hold instead: the file is loadable (the core
* rejects or crashes on a document whose CountInfo counts keyforms a stripped section no longer
* holds, and `runOracleDump` turns that into a failure), and the stripped feature is genuinely
* ABSENT from the evaluated result rather than merely unwritten in one section.
*
* That second half is what makes this more than a smoke test. Dropping a section without stripping
* the model produces a file that still loads: the drawables are all there, the geometry is right,
* and only the colours or the offscreens quietly read from the wrong place. The per-version
* invariants below fail on exactly that.
*
* Gated on `relive.dumpModel` + `relive.coreLib` + `moc3.samples`.
*/
class Moc3DowngradeOracleTest {
@Test
fun everyDowngradeLoadsAndDropsWhatItPromised() {
val dumpModel = requireOracleInput("relive.dumpModel")
val coreLib = requireOracleInput("relive.coreLib")
val samples =
System.getProperty("moc3.samples")
?.let(::File)
?.takeIf { it.isDirectory }
?.walkTopDown()
?.filter { it.isFile && it.extension == "moc3" && it.parentFile?.name != "work" }
?.sortedBy { it.name }
?.toList()
.orEmpty()
Assume.assumeTrue("[oracle] absent -Dmoc3.samples", samples.isNotEmpty())
val outputDir = File("build/moc3-downgrade").apply { mkdirs() }
val failures = ArrayList<String>()
var exported = 0
for (mocFile in samples) {
val source = runCatching { Moc3.decode(MocCodec.read(mocFile.readBytes())) }.getOrNull() ?: continue
val puppet = Moc3Import.fromMocDocument(source, displayInfo = null)
// The source's own drawable set is the reference: the ModelWithOffscreen family evaluates none
// at all (mesh-less parts and offscreens only), so "has drawables" is not a universal truth -
// "keeps the ones it had" is.
val sourceDrawables = runOracleDump(dumpModel, coreLib, mocFile, emptyMap()).entries.keys
for (version in MocVersion.entries) {
if (version.byteValue >= source.version.byteValue) {
continue
}
val (bytes, report) = Moc3Export.write(puppet, version)
val exportedFile =
File(outputDir, "${mocFile.nameWithoutExtension}-v${version.byteValue}.moc3")
.apply { writeBytes(bytes) }
exported++
// Loading IS the assertion here: runOracleDump fails the test on a non-zero exit, which is
// what a downgrade that left the file internally inconsistent produces.
val dump = runOracleDump(dumpModel, coreLib, exportedFile, emptyMap())
val subject = "${mocFile.name} -> v${version.byteValue}"
val lostDrawables = sourceDrawables - dump.entries.keys
if (lostDrawables.isNotEmpty()) {
failures.add("$subject: ${lostDrawables.size} drawables lost, e.g. ${lostDrawables.take(3)}")
}
// Offscreen rendering is moc 6; below it every isolated part is demoted to grouped.
if (dump.offscreens.isNotEmpty()) {
failures.add("$subject: ${dump.offscreens.size} offscreens survived the downgrade")
}
// Per-object multiply/screen color is moc 4; below it every drawable must evaluate to the
// identity pair, which is also what proves the color TABLES went with the sections.
if (version.byteValue < 4) {
for ((drawableId, entry) in dump.entries) {
if (oracleNeverEvaluated(entry)) {
continue
}
val tinted =
entry.multiplyRgba.take(3).any { channel -> channel != 1f } ||
entry.screenRgba.take(3).any { channel -> channel != 0f }
if (tinted) {
failures.add(
"$subject $drawableId: color survived a pre-4.2 downgrade " +
"(mul=${entry.multiplyRgba.take(3)} scr=${entry.screenRgba.take(3)})",
)
break
}
}
}
// A downgrade that removed nothing must say so: the corpus models all use something the
// oldest versions cannot carry, so a silent empty report means the strip did not run.
if (version == MocVersion.V30 && report.notices.none { it is ExportNotice.FeatureStripped }) {
val inUse =
puppet.parameters.isNotEmpty() &&
(
puppet.drawables.any { drawable -> drawable.blendShapes.isNotEmpty() } ||
puppet.parts.any { part -> part.isIsolated }
)
if (inUse) {
failures.add("$subject: features were stripped but nothing was reported")
}
}
}
}
assertTrue(exported > 0, "no corpus model has a version below its own")
println("[downgrade-oracle] $exported downgraded files loaded, ${failures.size} failures")
assertTrue(
failures.isEmpty(),
"downgraded exports are not clean:\n" + failures.take(20).joinToString("\n"),
)
}
/** A stripped feature is named by the report, and every notice names at least one subject. */
@Test
fun strippedFeaturesAreNamedInTheReport() {
val samples =
System.getProperty("moc3.samples")
?.let(::File)
?.takeIf { it.isDirectory }
?.walkTopDown()
?.filter { it.isFile && it.extension == "moc3" && it.parentFile?.name != "work" }
?.sortedBy { it.name }
?.toList()
.orEmpty()
// Assume, not println-and-return: a bare return reports PASSED, so an absent corpus would leave
// this gate green while covering nothing. Its sibling above gates the same way.
Assume.assumeTrue("[oracle] absent -Dmoc3.samples", samples.isNotEmpty())
val failures = ArrayList<String>()
val seenFeatures = linkedSetOf<RuntimeFeature>()
for (mocFile in samples) {
val source = runCatching { Moc3.decode(MocCodec.read(mocFile.readBytes())) }.getOrNull() ?: continue
val puppet = Moc3Import.fromMocDocument(source, displayInfo = null)
val report = Moc3Export.toMocDocument(puppet, MocVersion.V30).report
for (notice in report.notices.filterIsInstance<ExportNotice.FeatureStripped>()) {
seenFeatures.add(notice.feature)
if (notice.subjects.isEmpty()) {
failures.add("${mocFile.name}: ${notice.feature} was reported with no subjects")
}
}
}
println("[downgrade] features stripped somewhere in the corpus at v1: $seenFeatures")
assertTrue(seenFeatures.isNotEmpty(), "no corpus model exercised any strip")
assertTrue(failures.isEmpty(), failures.joinToString("\n"))
}
}
@@ -0,0 +1,223 @@
package org.umamo.render.eval
import org.junit.Assume
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.moc.MocCodec
import org.umamo.interop.moc3.export.Moc3Export
import org.umamo.interop.moc3.import.Moc3Import
import java.io.File
import kotlin.test.Test
import kotlin.test.assertTrue
/**
* The strongest gate available on the MOC3 export: import a corpus model, export it WITHOUT a
* reference container, and make the runtime evaluate both files.
*
* Our evaluator is out of the loop entirely here. Both sides run through the same core, so the
* comparison isolates the only question that matters - did the file we wrote encode the same rig -
* from the separate question of whether our own math matches theirs. A semantic round trip cannot
* do that: it compares our reading of our own output.
*
* "The export loads at all" is gated for free. `runOracleDump` fails the test when `dump_model`
* exits non-zero, and a file with a stale CountInfo, a mis-sized runtime-slot array, an off-by-one
* prefix sum, or a draw-group rule violation makes `csmReviveMocInPlace` reject it outright.
*
* `vuvH` is a free canary on the texcoord prefix sum (section 44), which nothing else exercises.
*
* Scoped to v1-v6 - every version the format models. Gated on `relive.dumpModel` +
* `relive.coreLib` + `moc3.samples`.
*/
class Moc3ExportOracleTest {
/** The versions the export currently covers in full. */
private val supportedVersions = setOf(1, 2, 3, 4, 5, 6)
@Test
fun exportedFilesEvaluateLikeTheirSources() {
val dumpModel = requireOracleInput("relive.dumpModel")
val coreLib = requireOracleInput("relive.coreLib")
val samples =
System.getProperty("moc3.samples")
?.let(::File)
?.takeIf { it.isDirectory }
?.walkTopDown()
?.filter { it.isFile && it.extension == "moc3" && it.parentFile?.name != "work" }
?.sortedBy { it.name }
?.toList()
.orEmpty()
Assume.assumeTrue("[oracle] absent -Dmoc3.samples", samples.isNotEmpty())
val outputDir = File("build/moc3-export").apply { mkdirs() }
val mismatches = ArrayList<String>()
var exported = 0
var comparedDrawables = 0
var comparedOffscreens = 0
var unevaluatedOffscreens = 0
for (mocFile in samples) {
val source = runCatching { Moc3.decode(MocCodec.read(mocFile.readBytes())) }.getOrNull() ?: continue
if (source.version.byteValue !in supportedVersions) {
continue
}
val puppet = Moc3Import.fromMocDocument(source, displayInfo = null)
val (bytes, report) = Moc3Export.write(puppet, source.version)
val exportedFile = File(outputDir, mocFile.name).apply { writeBytes(bytes) }
exported++
println("[export-oracle] ${mocFile.name}: ${bytes.size} bytes, ${report.notices.size} notices")
// The default pose alone is a real gate here: it exercises every static section plus the
// grid blend at each parameter's own default, which is where a mis-lowered binding shows up.
val sourceDump = runOracleDump(dumpModel, coreLib, mocFile, emptyMap())
val exportedDump = runOracleDump(dumpModel, coreLib, exportedFile, emptyMap())
for ((drawableId, expected) in sourceDump.entries) {
val actual = exportedDump.entries[drawableId]
if (actual == null) {
mismatches.add("${mocFile.name}: $drawableId missing from the exported file")
continue
}
if (oracleNeverEvaluated(expected)) {
continue
}
comparedDrawables++
if (!oracleCloseEnough(expected.vposH, actual.vposH)) {
mismatches.add("${mocFile.name} $drawableId vposH: ${expected.vposH} vs ${actual.vposH}")
}
if (!oracleCloseEnough(expected.vuvH, actual.vuvH)) {
mismatches.add("${mocFile.name} $drawableId vuvH: ${expected.vuvH} vs ${actual.vuvH}")
}
if (!oracleCloseEnough(expected.opacity.toDouble(), actual.opacity.toDouble())) {
mismatches.add("${mocFile.name} $drawableId op: ${expected.opacity} vs ${actual.opacity}")
}
compareChannel(mismatches, mocFile.name, drawableId, "mul", expected.multiplyRgba, actual.multiplyRgba)
compareChannel(mismatches, mocFile.name, drawableId, "scr", expected.screenRgba, actual.screenRgba)
}
// Offscreens (moc 6): the `O` lines carry the owner, the packed blend, the mask list, and the
// composite channels the runtime interpolated - the only end-to-end check that an isolated
// part's own layer survived the export.
//
// Everything positional is resolved to an ID first. The export re-derives part and drawable
// ordering from the runtime model, so the two files number the same objects differently, and a
// raw index comparison would report every offscreen in a reordered model as wrong while a
// genuinely misowned one hid among them.
val expectedOffscreens = sourceDump.offscreens.associateBy { sourceDump.partIds.getOrNull(it.ownerPartIndex) }
val actualOffscreens =
exportedDump.offscreens.associateBy { exportedDump.partIds.getOrNull(it.ownerPartIndex) }
for (ownerId in expectedOffscreens.keys - actualOffscreens.keys) {
mismatches.add("${mocFile.name}: offscreen owned by $ownerId missing from the exported file")
}
for (ownerId in actualOffscreens.keys - expectedOffscreens.keys) {
mismatches.add("${mocFile.name}: exported an offscreen owned by $ownerId that the source has not")
}
for ((ownerId, expected) in expectedOffscreens) {
val actual = actualOffscreens[ownerId] ?: continue
comparedOffscreens++
if (mocFile.name in offscreenChannelGap) {
// Structure is still compared below; only the interpolated channels are exempt.
unevaluatedOffscreens += if (actual.opacity != expected.opacity) 1 else 0
compareOffscreenStructure(mismatches, mocFile.name, ownerId, expected, actual, sourceDump, exportedDump)
continue
}
val subject = "offscreen($ownerId)"
compareOffscreenStructure(mismatches, mocFile.name, ownerId, expected, actual, sourceDump, exportedDump)
if (!oracleCloseEnough(expected.opacity.toDouble(), actual.opacity.toDouble())) {
mismatches.add("${mocFile.name} $subject op: ${expected.opacity} vs ${actual.opacity}")
}
compareChannel(mismatches, mocFile.name, subject, "mul", expected.multiplyRgba, actual.multiplyRgba)
compareChannel(mismatches, mocFile.name, subject, "scr", expected.screenRgba, actual.screenRgba)
}
}
assertTrue(exported > 0, "no corpus model in the export's supported versions")
println(
"[export-oracle] $exported models exported and re-evaluated, $comparedDrawables drawables and " +
"$comparedOffscreens offscreens compared ($unevaluatedOffscreens in the pinned s160 gap), " +
"${mismatches.size} mismatches",
)
assertTrue(
mismatches.isEmpty(),
"exported files do not evaluate like their sources:\n" + mismatches.take(20).joinToString("\n"),
)
}
/**
* Models whose offscreen CHANNELS are a known gap; their structure is still compared.
*
* The runtime drives offscreen evaluation from section 160, not from the owner column: blanking 160
* in an exported file leaves every offscreen at zero, and filling it for every part evaluates all of
* them. Its slots are NOT the owner parts - in modelA the two columns name different parts for 13 of
* 24 offscreens - so 160 is keyed by whichever part the runtime's own walk reaches, which we cannot
* yet reconstruct. The export writes the owner-consistent inverse, and on modelA the runtime then
* never reaches 12 of the 24, leaving them unevaluated (opacity 0, multiply 0,0,0).
*
* Every other corpus model matches exactly, including the whole ModelWithOffscreen family, because
* their part numbering survives the export unchanged. Remove this the moment 160's key is pinned.
*/
private val offscreenChannelGap = setOf("modelA.moc3")
/**
* Compares an offscreen's static fields - blend, flags, and the clip set by drawable id.
*
* @param ArrayList mismatches The shared collector.
* @param String fileName The model being compared.
* @param String? ownerId The owner part id.
* @param OracleOffscreen expected The source file's offscreen.
* @param OracleOffscreen actual The exported file's offscreen.
* @param OracleDump sourceDump The source dump, for its drawable ids.
* @param OracleDump exportedDump The exported dump, for its drawable ids.
*/
private fun compareOffscreenStructure(
mismatches: ArrayList<String>,
fileName: String,
ownerId: String?,
expected: OracleOffscreen,
actual: OracleOffscreen,
sourceDump: OracleDump,
exportedDump: OracleDump,
) {
val subject = "offscreen($ownerId)"
if (expected.blendMode != actual.blendMode) {
mismatches.add("$fileName $subject blend: ${expected.blendMode} vs ${actual.blendMode}")
}
if (expected.constantFlags != actual.constantFlags) {
mismatches.add("$fileName $subject cflag: ${expected.constantFlags} vs ${actual.constantFlags}")
}
val expectedMasks = expected.maskIndices.mapNotNull { sourceDump.drawableIds.getOrNull(it) }
val actualMasks = actual.maskIndices.mapNotNull { exportedDump.drawableIds.getOrNull(it) }
// Order is not compared: a clip set is a set, and the export emits it in the runtime model's own
// order rather than the source file's.
if (expectedMasks.toSet() != actualMasks.toSet()) {
mismatches.add("$fileName $subject masks: $expectedMasks vs $actualMasks")
}
}
/**
* Compares one RGBA channel row, recording a mismatch per differing component.
*
* @param ArrayList mismatches The shared collector.
* @param String fileName The model being compared.
* @param String subject The drawable id or offscreen being compared.
* @param String channel The channel name for the message.
* @param List expected The source file's row.
* @param List actual The exported file's row.
*/
private fun compareChannel(
mismatches: ArrayList<String>,
fileName: String,
subject: String,
channel: String,
expected: List<Float>,
actual: List<Float>,
) {
if (expected.size != actual.size) {
mismatches.add("$fileName $subject $channel arity: ${expected.size} vs ${actual.size}")
return
}
for (component in expected.indices) {
if (!oracleCloseEnough(expected[component].toDouble(), actual[component].toDouble())) {
mismatches.add("$fileName $subject $channel[$component]: ${expected[component]} vs ${actual[component]}")
return
}
}
}
}

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