Define Proposal 3 artwork contract

Author: trekawek

ui-portable/README.md

@@ -0,0 +1,56 @@
+# Portable Proposal 3 artwork contract
+
+This module owns the portable menu model and the future decoding/composition contract for Proposal
+3. Android and desktop adapters will only blit the ARGB result supplied by the portable compositor
+and map controller/touch input through the portable geometry; they must not reinterpret, crop,
+reflow, or stretch the visual contract.
+
+## Provenance, fixtures, and license
+
+The 14 source images are the original 1672x941 Proposal 3 compositions from
+`output/imagegen/proposal-3-menu-tree/`. The repository keeps those originals only in the existing
+untracked `output/` directory. This revision stores no artwork in `src/main/resources`, so it does
+not add the 22 MiB source set to an APK or desktop runtime artifact.
+
+For contract tests, each source was transformed mechanically with
+`ffmpeg -vf crop=924:736:374:102` and losslessly optimized with `optipng -o2`. The resulting
+924x736 RGB, non-interlaced PNGs live under
+`src/test/resources/eu/rekawek/coffeegb/ui/menu/artwork/proposal3/source/`. Tests pin each encoded
+PNG SHA-256 and decode its PNG filters in pure Java to pin the raw RGB frame SHA-256 produced by the
+same ffmpeg crop. This is the lossless raw-pixel verification that guards the canonical crop and
+does not require ImageIO or a platform image library.
+
+The repository is distributed under the MIT license in the root `LICENSE` file. This module does
+not add a separate artwork license or alter the source provenance; the imported fixtures retain the
+repository's applicable license and notices.
+
+## Canonical visual authority
+
+The original composition geometry is 1672x941. `MenuArtworkCatalog.SOURCE_VISIBLE_CROP` is
+`x=374, y=102, width=924, height=736`, and every packaged test fixture is already that crop. The
+fixture itself is the complete image to decode and blit; hosts must not crop it again at runtime.
+Each route also retains its original source filename for provenance.
+
+Dynamic content is overlays-only: later compositor work may place the ROM name, sliders, focus
+state, or status values above the immutable artwork, but must not redraw or reflow the base visual.
+The Android file browser remains a native boundary. Open/import actions hand off to Android's native
+document picker; this portable UI never draws a filesystem browser.
+
+## Integer aspect-fit placement
+
+`MenuViewport` places the 924x736 image into any positive integer viewport with one aspect-fit
+placement. It uses long cross-products and floor rounding, centers with integer left/top offsets,
+and assigns odd remainder pixels to the right/bottom bars. `contentBounds()` is half-open:
+`[left,right) x [top,bottom)`. Inverse input mapping returns `Optional`/`OptionalInt` and rejects
+letterbox pixels and the right/bottom edges.
+
+Portrait and desktop hosts must preserve this placement rather than reflowing or independently
+stretching either axis. The known portrait aperture `758x685` produces `[0,41,758,644)`; the
+remaining pixels are letterbox bars.
+
+## Future runtime paths
+
+The `source/` path is intentionally test-fixture-only. A later sanitized compositor PR will own
+the production runtime route and/or atlas paths in `src/main/resources`, decode and compose them in
+`ui-portable`, and expose only ARGB blit data plus the portable input mapping to Android and desktop
+adapters. No host adapter should depend on this fixture path or on raw resource streams.

ui-portable/src/main/java/eu/rekawek/coffeegb/ui/menu/artwork/MenuArtwork.java

@@ -0,0 +1,73 @@
+package eu.rekawek.coffeegb.ui.menu.artwork;
+
+import eu.rekawek.coffeegb.ui.menu.MenuRoute;
+
+import java.io.InputStream;
+import java.util.Objects;
+
+/**
+ * Immutable metadata for one packaged canonical Proposal 3 menu crop.
+ *
+ * <p>The packaged image is already the complete 924x736 visible screen. The original 1672x941
+ * composition and its {@link #sourceVisibleCrop()} are retained only as provenance. The portable
+ * module owns the future decode/composition contract; platform adapters consume the resulting
+ * ARGB pixels and map input through {@link MenuViewport}.
+ */
+public final class MenuArtwork {
+
+    private final MenuRoute route;
+    private final String sourceFilename;
+    private final String resourcePath;
+    private final MenuRect sourceVisibleCrop;
+
+    MenuArtwork(MenuRoute route, String sourceFilename, String resourcePath, MenuRect sourceVisibleCrop) {
+        this.route = Objects.requireNonNull(route, "route");
+        this.sourceFilename = Objects.requireNonNull(sourceFilename, "sourceFilename");
+        this.resourcePath = Objects.requireNonNull(resourcePath, "resourcePath");
+        this.sourceVisibleCrop = Objects.requireNonNull(sourceVisibleCrop, "sourceVisibleCrop");
+        if (sourceFilename.isEmpty()) {
+            throw new IllegalArgumentException("sourceFilename must not be empty");
+        }
+        if (resourcePath.isEmpty() || resourcePath.charAt(0) != '/') {
+            throw new IllegalArgumentException("Artwork resource paths must be absolute classpath paths");
+        }
+    }
+
+    public MenuRoute route() {
+        return route;
+    }
+
+    /** Returns the original Proposal 3 source filename associated with this crop. */
+    public String sourceFilename() {
+        return sourceFilename;
+    }
+
+    /** Returns the crop coordinates in the original 1672x941 source composition. */
+    public MenuRect sourceVisibleCrop() {
+        return sourceVisibleCrop;
+    }
+
+    /** Returns the dimensions of the already-cropped packaged image. */
+    public int packagedWidth() {
+        return MenuArtworkCatalog.PACKAGED_WIDTH;
+    }
+
+    /** Returns the dimensions of the already-cropped packaged image. */
+    public int packagedHeight() {
+        return MenuArtworkCatalog.PACKAGED_HEIGHT;
+    }
+
+    /* Fixture-only access; production runtime paths belong to the later compositor integration. */
+    String resourcePath() {
+        return resourcePath;
+    }
+
+    /* Fixture-only access; callers receive a 924x736 image and must close the stream. */
+    InputStream openStream() {
+        InputStream stream = MenuArtwork.class.getResourceAsStream(resourcePath);
+        if (stream == null) {
+            throw new IllegalStateException("Missing menu artwork resource: " + resourcePath);
+        }
+        return stream;
+    }
+}

ui-portable/src/main/java/eu/rekawek/coffeegb/ui/menu/artwork/MenuArtworkCatalog.java

@@ -0,0 +1,100 @@
+package eu.rekawek.coffeegb.ui.menu.artwork;
+
+import eu.rekawek.coffeegb.ui.menu.MenuRoute;
+
+import java.util.Collections;
+import java.util.EnumMap;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+
+/**
+ * The canonical Proposal 3 artwork catalog.
+ *
+ * <p>The source PNGs are complete 1672x941 compositions, but the test fixtures packaged by this
+ * revision are already the fixed 924x736 crop declared by {@link #SOURCE_VISIBLE_CROP}. Runtime
+ * route/atlas paths are reserved for the later sanitized compositor integration.
+ */
+public final class MenuArtworkCatalog {
+
+    /** Width of every original Proposal 3 composition in pixels. */
+    public static final int SOURCE_WIDTH = 1672;
+
+    /** Height of every original Proposal 3 composition in pixels. */
+    public static final int SOURCE_HEIGHT = 941;
+
+    /** Width of each lossless packaged canonical crop. */
+    public static final int PACKAGED_WIDTH = 924;
+
+    /** Height of each lossless packaged canonical crop. */
+    public static final int PACKAGED_HEIGHT = 736;
+
+    /** Original-composition crop retained as provenance for every packaged image. */
+    public static final MenuRect SOURCE_VISIBLE_CROP = new MenuRect(374, 102, 924, 736);
+
+    /** The complete bounds of each packaged image. */
+    public static final MenuRect PACKAGED_BOUNDS = new MenuRect(0, 0, PACKAGED_WIDTH, PACKAGED_HEIGHT);
+
+    private static final String FIXTURE_RESOURCE_ROOT =
+            "/eu/rekawek/coffeegb/ui/menu/artwork/proposal3/source/";
+
+    private static final Map<MenuRoute, MenuArtwork> ARTWORK = createCatalog();
+
+    private MenuArtworkCatalog() {
+    }
+
+    /** Returns the one canonical artwork entry for a route. */
+    public static MenuArtwork artwork(MenuRoute route) {
+        return ARTWORK.get(Objects.requireNonNull(route, "route"));
+    }
+
+    /** Returns an immutable route-to-artwork view containing every menu route exactly once. */
+    public static Map<MenuRoute, MenuArtwork> all() {
+        return ARTWORK;
+    }
+
+    private static Map<MenuRoute, MenuArtwork> createCatalog() {
+        EnumMap<MenuRoute, MenuArtwork> catalog = new EnumMap<>(MenuRoute.class);
+        add(catalog, MenuRoute.PAUSE_CONSOLE, "00-pause-console.png");
+        add(catalog, MenuRoute.SAVE_STATES, "01-save-states.png");
+        add(catalog, MenuRoute.SETTINGS, "02-settings.png");
+        add(catalog, MenuRoute.AUDIO, "03-audio.png");
+        add(catalog, MenuRoute.TOUCH_CONTROLS, "04-touch-controls.png");
+        add(catalog, MenuRoute.CONTROLLER_MAPPING, "05-controller-mapping.png");
+        add(catalog, MenuRoute.OPTIONAL_DEVICES, "06-optional-devices.png");
+        add(catalog, MenuRoute.DATA_MEDIA, "07-data-media.png");
+        add(catalog, MenuRoute.LIBRARY, "08-library.png");
+        add(catalog, MenuRoute.CHOOSE_ROM, "09-choose-rom.png");
+        add(catalog, MenuRoute.SYSTEM, "10-system.png");
+        add(catalog, MenuRoute.ABOUT, "11-about.png");
+        add(catalog, MenuRoute.CONFIRM_ACTION, "12-confirm-action.png");
+        add(catalog, MenuRoute.PRINTER_PAPER, "13-printer-paper.png");
+
+        if (catalog.size() != MenuRoute.values().length) {
+            throw new IllegalStateException("Proposal 3 artwork catalog does not cover every route");
+        }
+        Set<String> paths = new HashSet<>();
+        for (MenuRoute route : MenuRoute.values()) {
+            MenuArtwork artwork = catalog.get(route);
+            if (artwork == null || !paths.add(artwork.resourcePath())) {
+                throw new IllegalStateException("Proposal 3 artwork catalog contains a duplicate or missing route");
+            }
+        }
+        return Collections.unmodifiableMap(catalog);
+    }
+
+    private static void add(EnumMap<MenuRoute, MenuArtwork> catalog, MenuRoute route, String filename) {
+        if (catalog.containsKey(route)) {
+            throw new IllegalStateException("Duplicate artwork route: " + route);
+        }
+        MenuArtwork artwork = new MenuArtwork(route, filename, FIXTURE_RESOURCE_ROOT + filename,
+                SOURCE_VISIBLE_CROP);
+        for (MenuArtwork existing : catalog.values()) {
+            if (existing.resourcePath().equals(artwork.resourcePath())) {
+                throw new IllegalStateException("Duplicate artwork resource: " + artwork.resourcePath());
+            }
+        }
+        catalog.put(route, artwork);
+    }
+}

ui-portable/src/main/java/eu/rekawek/coffeegb/ui/menu/artwork/MenuPoint.java

@@ -0,0 +1,11 @@
+package eu.rekawek.coffeegb.ui.menu.artwork;
+
+/** An immutable point in a menu source or destination coordinate space. */
+public record MenuPoint(double x, double y) {
+
+    public MenuPoint {
+        if (!Double.isFinite(x) || !Double.isFinite(y)) {
+            throw new IllegalArgumentException("Menu coordinates must be finite");
+        }
+    }
+}

ui-portable/src/main/java/eu/rekawek/coffeegb/ui/menu/artwork/MenuRect.java

@@ -0,0 +1,31 @@
+package eu.rekawek.coffeegb.ui.menu.artwork;
+
+/**
+ * An immutable integer rectangle represented as {@code [x, right) x [y, bottom)}.
+ */
+public record MenuRect(int x, int y, int width, int height) {
+
+    public MenuRect {
+        if (x < 0 || y < 0 || width <= 0 || height <= 0) {
+            throw new IllegalArgumentException("A menu rectangle must be non-empty and non-negative");
+        }
+        if ((long) x + width > Integer.MAX_VALUE || (long) y + height > Integer.MAX_VALUE) {
+            throw new IllegalArgumentException("A menu rectangle must fit in integer coordinates");
+        }
+    }
+
+    /** Returns the exclusive right edge. */
+    public int right() {
+        return x + width;
+    }
+
+    /** Returns the exclusive bottom edge. */
+    public int bottom() {
+        return y + height;
+    }
+
+    /** Returns whether an integer point is inside this half-open rectangle. */
+    public boolean contains(int pointX, int pointY) {
+        return pointX >= x && pointX < right() && pointY >= y && pointY < bottom();
+    }
+}