feat(ds): Metal sub-rectangle dual-screen rendering for Nintendo DS

Implements GPU-side split rendering for DS dual-screen skins.

- Add `dual_screen_blit.metal` shader for sub-rectangle blitting
- Add `PVMetalViewController+DualScreen` with DualScreenRenderInfo,
  pipeline setup, and single-pass dual-screen render method
- Add `dualScreenLayout` and `dualScreenBlitPipeline` properties to
  PVMetalViewController; hook into directRender
- Add `PVEmulatorViewController+MetalDualScreen` to compute per-screen
  DualScreenRenderInfo from the active skin's DeltaSkinScreen groups and
  install them on PVMetalViewController
- Route DS dual-screen applyDualScreenViewport through the Metal path
  when a compatible skin is active; clear layout when skins are disabled
- Enable supportsSkins=true for PVMelonDSCore and PVDesmume2015Core

The combined 256×384 DS framebuffer is split into top (y=0..191) and
bottom (y=192..383) sub-rectangles, each rendered to the viewport
position defined by the skin's DeltaSkinScreen.outputFrame.

Part of #3373

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: github-actions[bot]

Cores/Desmume2015/PVDesmume2015Core/Core/PVDesmume2015Core.swift

@@ -15,8 +15,8 @@ import PVCoreBridgeRetro
 @objc
 @objcMembers
 open class PVDesmume2015Core: PVEmulatorCore {
-    /// Dual-screen skin layouts are not yet supported; disable until implemented.
-    public override var supportsSkins: Bool { false }
+    /// Metal sub-rectangle dual-screen rendering is now implemented.
+    public override var supportsSkins: Bool { true }
 
     public override var supportsDualScreens: Bool { true }
 

Cores/melonDS/PVMelonDSCore/Core/PVMelonDSCore.swift

@@ -18,8 +18,8 @@ import PVCoreBridgeRetro
 // to the melonDS run-loop thread (main thread). PVMelonDSCore+PVNetplayCapable
 // dispatches via MainActor.run to preserve this invariant.
 public final class PVMelonDSCore: PVEmulatorCore, @unchecked Sendable {
-    /// Dual-screen skin layouts are not yet supported; disable until implemented.
-    public override var supportsSkins: Bool { false }
+    /// Metal sub-rectangle dual-screen rendering is now implemented.
+    public override var supportsSkins: Bool { true }
 
     public override var supportsDualScreens: Bool { true }
 

PVShaders/Sources/PVShaders/Resources/Metal/Blitters/dual_screen_blit.metal

@@ -0,0 +1,46 @@
+// dual_screen_blit.metal
+// PVShaders
+//
+// Metal shaders for DS dual-screen sub-rectangle blitting.
+//
+// Each screen is rendered by a separate draw call in a single render pass.
+// The vertex buffer carries interleaved (NDC-position, UV) data so the vertex
+// function needs no uniforms — all per-screen geometry is baked in by the CPU.
+//
+// Usage pattern (per screen):
+//   1. Compute 4 vertices of the form float4(ndcX, ndcY, srcU, srcV)
+//      arranged as a triangle-strip  (TL, TR, BL, BR).
+//   2. Call setVertexBytes(_:length:index:) with buffer index 0.
+//   3. drawPrimitives(.triangleStrip, vertexStart: 0, vertexCount: 4)
+//
+// The fragment shader samples 'source' at the UV carried from the vertex stage.
+// flipY is handled on the CPU (swap V0/V1 when the texture is OpenGL-origin).
+
+#include <metal_stdlib>
+using namespace metal;
+
+struct DualScreenVSOut {
+    float4 position [[position]];
+    float2 texCoord;
+};
+
+// vertices[vid] = (NDC.x, NDC.y, UV.u, UV.v)
+vertex DualScreenVSOut dual_screen_vs(
+    uint              vid      [[vertex_id]],
+    constant float4  *vertices [[buffer(0)]])
+{
+    DualScreenVSOut out;
+    out.position = float4(vertices[vid].xy, 0.0f, 1.0f);
+    out.texCoord = vertices[vid].zw;
+    return out;
+}
+
+fragment half4 dual_screen_ps(
+    DualScreenVSOut         in     [[stage_in]],
+    texture2d<half>         source [[texture(0)]],
+    sampler                 samp   [[sampler(0)]])
+{
+    half4 color = source.sample(samp, in.texCoord);
+    color.a = 1.0h;
+    return color;
+}

PVUI/Sources/PVUIBase/PVEmulatorVC/PVEmulatorViewController+DualScreen.swift

@@ -213,6 +213,20 @@ extension PVEmulatorViewController {
             return
         }
 
+        // Metal dual-screen path: for DS cores (melonDS, DeSmuME) with an active
+        // skin, hand the sub-rectangle layout to PVMetalViewController so it can
+        // render both screens in a single GPU pass instead of resizing the view.
+        if canUseMetalDualScreenRendering {
+            if applyMetalDualScreenLayout() {
+                DLOG("🎮 Applied Metal dual-screen layout")
+                return
+            }
+            // Layout computation failed — fall through to the legacy path.
+        } else {
+            // Skin disabled or core not Metal-based; clear any stale layout.
+            clearMetalDualScreenLayout()
+        }
+
         // Ensure GPU view is visible and properly layered before positioning
         ensureGPUViewVisibilityAndZOrder()
 

PVUI/Sources/PVUIBase/PVEmulatorVC/PVEmulatorViewController+MetalDualScreen.swift

@@ -0,0 +1,197 @@
+// PVEmulatorViewController+MetalDualScreen.swift
+// PVUI
+//
+// Bridges the DeltaSkin layout system to the Metal dual-screen sub-rectangle
+// renderer in PVMetalViewController.
+//
+// When a dual-screen game (e.g. Nintendo DS) is running with an active skin:
+//   1. The skin describes where each screen should appear via DeltaSkinScreen.
+//   2. This extension computes DualScreenRenderInfo values from those descriptions
+//      and installs them on PVMetalViewController.
+//   3. PVMetalViewController then splits the combined framebuffer (e.g. 256×384
+//      for DS) into two independently-positioned viewports in a single pass.
+//
+// Called from applyDualScreenViewport() in PVEmulatorViewController+DualScreen.
+
+import UIKit
+import PVEmulatorCore
+import PVLogging
+
+// MARK: - Metal Dual-Screen Layout
+
+extension PVEmulatorViewController {
+
+    // MARK: Public API
+
+    /// Returns `true` when all conditions for Metal sub-rectangle dual-screen
+    /// rendering are met:
+    ///   • the GPU view controller is a `PVMetalViewController`
+    ///   • the emulator core declares dual-screen support
+    ///   • a DeltaSkin with screen-group data is active
+    ///   • we are NOT running on tvOS (skins are disabled there)
+    var canUseMetalDualScreenRendering: Bool {
+        #if os(tvOS)
+        return false
+        #else
+        guard gpuViewController is PVMetalViewController else { return false }
+        guard core.supportsDualScreens else { return false }
+        guard isDeltaSkinEnabled, currentSkin != nil else { return false }
+        return true
+        #endif
+    }
+
+    /// Computes the Metal dual-screen layout from the current skin and installs it
+    /// on the `PVMetalViewController`.  Also expands the Metal view to fill the
+    /// parent view so Metal can position each screen freely.
+    ///
+    /// Call this instead of `applyFrameToGPUView` when `canUseMetalDualScreenRendering`
+    /// is `true`.
+    ///
+    /// - Returns: `true` if the layout was successfully applied.
+    @discardableResult
+    func applyMetalDualScreenLayout() -> Bool {
+        guard let metalVC = gpuViewController as? PVMetalViewController else { return false }
+        guard isDeltaSkinEnabled, let skin = currentSkin else { return false }
+
+        #if !os(tvOS)
+        let skinDevice: DeltaSkinDevice = UIDevice.current.userInterfaceIdiom == .pad ? .ipad : .iphone
+        #else
+        let skinDevice: DeltaSkinDevice = .tv
+        #endif
+        let orientation: DeltaSkinOrientation = view.bounds.width > view.bounds.height ? .landscape : .portrait
+        let traits = DeltaSkinTraits(device: skinDevice,
+                                     displayType: .standard,
+                                     orientation: orientation,
+                                     gameIdentifier: game?.title)
+
+        // We need a skin with at least two screens in a screen group.
+        guard let screenGroups = skin.screenGroups(for: traits),
+              let group = screenGroups.first,
+              group.screens.count >= 2 else {
+            DLOG("dual-screen metal: skin has no screen groups with 2+ screens, falling back")
+            metalVC.dualScreenLayout = nil
+            return false
+        }
+
+        // Input-texture dimensions — used to normalise the skin's inputFrame.
+        let bufferSize = core.bufferSize
+        let texW = bufferSize.width > 0 ? bufferSize.width : 256
+        let texH = bufferSize.height > 0 ? bufferSize.height : 384
+
+        // View layout parameters (mirrors currentDualScreenViewportFrame()).
+        let viewSize = view.bounds.size
+        guard viewSize.width > 0, viewSize.height > 0 else { return false }
+
+        guard let mappingSize = skin.mappingSize(for: traits),
+              mappingSize.width > 0, mappingSize.height > 0 else { return false }
+
+        // Scale factor: fit the skin's mapping size into the view.
+        // Mirrors the calculation in currentDualScreenViewportFrame().
+        let isPortraitPhone = skinDevice == .iphone && orientation == .portrait
+        let scale: CGFloat
+        if isPortraitPhone {
+            let ws = viewSize.width  / mappingSize.width
+            let hs = viewSize.height / mappingSize.height
+            scale = ws * mappingSize.height <= viewSize.height ? ws : min(ws, hs)
+        } else {
+            scale = min(viewSize.width  / mappingSize.width,
+                        viewSize.height / mappingSize.height)
+        }
+
+        let scaledW = mappingSize.width  * scale
+        let scaledH = mappingSize.height * scale
+        let xOff = (viewSize.width  - scaledW) / 2
+        let yOff: CGFloat = isPortraitPhone ? viewSize.height - scaledH
+                                            : (viewSize.height - scaledH) / 2
+
+        // Sort screens top-to-bottom by their outputFrame Y value.
+        let sorted = group.screens.sorted { a, b in
+            (a.outputFrame?.minY ?? 0) < (b.outputFrame?.minY ?? 0)
+        }
+
+        var renderInfos: [DualScreenRenderInfo] = []
+
+        for (index, screen) in sorted.enumerated() {
+            guard let outputFrame = screen.outputFrame else { continue }
+
+            // --- Source UV ---
+            // Use skin-specified inputFrame if available; otherwise default to
+            // equal halves of the combined framebuffer (DS convention).
+            let srcRect: CGRect
+            if let inFrame = screen.inputFrame, inFrame.width > 0, inFrame.height > 0 {
+                srcRect = CGRect(x: inFrame.minX / texW,
+                                 y: inFrame.minY / texH,
+                                 width: inFrame.width  / texW,
+                                 height: inFrame.height / texH)
+            } else {
+                // Default: split the framebuffer into equal vertical halves.
+                let halfH: CGFloat = 0.5
+                srcRect = CGRect(x: 0, y: CGFloat(index) * halfH, width: 1, height: halfH)
+            }
+
+            // --- Destination (view-space points) ---
+            // Mirror the calculation in currentDualScreenViewportFrame() exactly.
+            let inLayout = CGRect(x: outputFrame.minX * scaledW,
+                                  y: outputFrame.minY * scaledH,
+                                  width:  outputFrame.width  * scaledW,
+                                  height: outputFrame.height * scaledH)
+            let destRect = CGRect(x: xOff + inLayout.midX - inLayout.width  / 2,
+                                  y: yOff + inLayout.midY - inLayout.height / 2,
+                                  width:  inLayout.width,
+                                  height: inLayout.height)
+
+            renderInfos.append(DualScreenRenderInfo(normalizedSourceRect: srcRect,
+                                                    viewDestRect: destRect))
+        }
+
+        guard renderInfos.count >= 2 else {
+            DLOG("dual-screen metal: could not compute 2+ render infos, falling back")
+            metalVC.dualScreenLayout = nil
+            return false
+        }
+
+        ILOG("dual-screen metal: installing layout with \(renderInfos.count) screens")
+        metalVC.dualScreenLayout = renderInfos
+
+        // Expand the Metal view to fill the parent so both screen quads are visible.
+        expandMetalViewToFillParent(metalVC)
+        return true
+    }
+
+    /// Removes the Metal dual-screen layout (reverts to standard fullscreen blit).
+    func clearMetalDualScreenLayout() {
+        (gpuViewController as? PVMetalViewController)?.dualScreenLayout = nil
+    }
+
+    // MARK: Helpers
+
+    /// Expands the Metal view controller's view to fill `self.view` so the dual-screen
+    /// quads can be positioned freely anywhere within the screen.
+    private func expandMetalViewToFillParent(_ metalVC: PVMetalViewController) {
+        let fullFrame = view.bounds
+
+        (metalVC as PVGPUViewController).useCustomPositioning = true
+        (metalVC as PVGPUViewController).customFrame = fullFrame
+
+        metalVC.view.autoresizingMask = []
+        metalVC.mtlView.autoresizingMask = []
+
+        UIView.performWithoutAnimation {
+            metalVC.view.frame  = fullFrame
+            metalVC.mtlView.frame = metalVC.view.bounds
+        }
+
+        let drawScale = metalVC.renderSettings.nativeScaleEnabled
+            ? (metalVC.view.window?.screen.scale ?? UIScreen.main.scale)
+            : 1.0
+        metalVC.mtlView.drawableSize     = CGSize(width:  fullFrame.width  * drawScale,
+                                                  height: fullFrame.height * drawScale)
+        metalVC.mtlView.contentScaleFactor = drawScale
+        metalVC.view.isHidden    = false
+        metalVC.mtlView.isHidden = false
+
+        ensureGPUViewVisibilityAndZOrder()
+
+        DLOG("dual-screen metal: expanded Metal view to full frame \(fullFrame)")
+    }
+}