[Epic] Native libretro.h Frontend API

[github-actions]

Overview

This epic tracks all work required to implement a full native libretro.h frontend API in Provenance — without relying on the RetroArch binary/dylib wrapper. The goal is to allow hardware-accelerated libretro cores (Flycast, BeetlePSX, Play!, etc.) to render video natively through Provenance's Metal pipeline, on iOS, tvOS, and macOS/Catalyst.

Context

Currently, hardware-accelerated libretro cores can only run via the RetroArch dylib wrapper (PVCoreBridgeRetro backed by the full RetroArch binary). This works but has significant downsides:

• Large binary overhead (full RetroArch runtime required)
• Cannot be included in Provenance Lite builds
• Poor integration with Provenance's native UI (save states, cheats, overlays)
• Excluded from the direct libretro bridge path (PVLibRetroCoreBridge)

The spike in #2624 confirms what needs to be built. This epic replaces the RetroArch middleman for hardware-accelerated cores.

Architecture Target

libretro core (Flycast, BeetlePSX, Play!, etc.)
        |
        v RETRO_ENVIRONMENT_SET_HW_RENDER
PVLibRetroGLESCoreBridge
        |
        +-- OpenGL ES path: EAGLContext -> FBO -> MTLTexture blit
        +-- Vulkan path:    MoltenVK VkInstance -> CAMetalLayer -> MTLTexture
        |
        v
PVMetalViewController (existing Metal display pipeline)

Sub-Tasks

• [P0] [libretro][P0] OpenGL ES FBO -> Metal texture blit pipeline #2632 OpenGL ES FBO -> Metal texture blit pipeline (critical path for Flycast/BeetlePSX)
• [P1] [libretro][P1] Thread-safe GL context lifecycle + retro_run frame loop #2633 Thread-safe GL context lifecycle + retro_run frame loop
• [P1] [libretro][P1] Vulkan/MoltenVK -> CAMetalLayer surface integration #2634 Vulkan/MoltenVK -> CAMetalLayer surface integration
• [P1] [libretro][P1] Complete environment callback coverage for iOS/tvOS/Catalyst #2635 Complete libretro environment callback coverage for iOS/tvOS/Catalyst
• [P2] [libretro][P2] RETRO_ENVIRONMENT_GET_PREFERRED_HW_RENDER + Vulkan context negotiation #2638 RETRO_ENVIRONMENT_GET_PREFERRED_HW_RENDER + context negotiation interface
• [P1] [Core][P1] Flycast: fix video output via native libretro HW render path #2636 Flycast: fix video output via native libretro HW render
• [P1] [Core][P1] BeetlePSX: fix video output via native libretro HW render path #2637 BeetlePSX: fix video output via native libretro HW render
• [P2] [libretro][P2] Decouple native libretro bridge from RetroArch runtime #2639 Decouple native libretro bridge from RetroArch runtime

Dependency Graph

#2632 (OpenGL ES FBO->Metal)  <-- BLOCKS --> #2636 (Flycast video)
#2633 (GL context lifecycle)  <-- BLOCKS --> #2636, #2637
#2635 (env callbacks)         <-- BLOCKS --> #2637 (BeetlePSX)
#2634 (Vulkan/MoltenVK)       <-- BLOCKS --> #2637 (Vulkan path)
#2638 (preferred HW render)   <-- PART OF --> #2635
#2639 (decouple RetroArch)    <-- enables Lite builds

References

• Spike / design: [Spike] libretro RETRO_ENVIRONMENT_SET_HW_RENDER bridge for OpenGL/Vulkan cores #2624
• Core Updates epic: [Epic] Core Updates - Fix and update out-of-date native cores #2482
• Flycast original: [Core] Flycast Redo 1 #2369
• BeetlePSX original: [Core] Beetle PSX #2368
• Original new cores PR: Feature/new cores/libretrogles #2373
• DuckStation (partial Vulkan/MoltenVK reference): Cores/DuckStation/PVDuckStation/PVDuckStationCoreBridge.mm