feat(macos/input): implement host-side virtual gamepad via IOHIDUserDevice

Upstream Sunshine on macOS has no host-side gamepad support: every
alloc_gamepad/gamepad_update/free_gamepad in src/platform/macos/input.cpp
is a stub that logs "Gamepad not yet implemented for MacOS" and returns
failure, and get_capabilities() returns 0. Moonlight clients send
gamepad events over the wire that the host silently drops.

This ports Lumen's working approach (MIT-licensed; trollzem/Lumen):
publish a virtual gamepad as an IOHIDUserDevice with a complete HID
report descriptor (16 buttons, 4-bit hat switch, 2x 8-bit triggers,
4x 16-bit signed stick axes). macOS's HID matching publishes the
device to userspace; games, emulators, GameController.framework, SDL,
and Steam all see it as a real USB Xbox-style controller (VID 0x1209,
PID 0x5853 — pid.codes open-source range, intentionally not in SDL's
known-controller database so it routes through generic mapping).

The IOHIDUserDevice creation path requires AMFI to be bypassed at
boot: `sudo nvram boot-args="amfi_get_out_of_my_way=1"` and reboot.
Without that, IOHIDUserDeviceCreateWithProperties fails the entitlement
check and the probe at input() construction time logs a clear
instruction. SIP can stay on. The DriverKit DEXT path (no AMFI flag,
requires Apple DriverKit entitlement application + signed
system-extension distribution) is the longer-term shipping story but
is multi-week work; this gets us to a working gamepad host today.

Changes:
- src/platform/macos/hid_gamepad.{h,m} (new): MRC Obj-C wrapper around
  IOHIDUserDevice publishing the Xbox-style gamepad HID descriptor.
  Maps Sunshine's 32-bit buttonFlags to the 16-bit HID button field +
  4-bit hat switch + axes/triggers. Bounded 2s teardown via
  IOHIDUserDeviceSetCancelHandler. QOS_CLASS_USER_INTERACTIVE serial
  queue for report dispatch.
- src/platform/macos/input.{cpp -> mm}: renamed to Obj-C++ so the
  gamepad path holds HIDGamepad strong references directly. Mouse/
  keyboard injection paths unchanged. macos_input_t gains a 16-slot
  HIDGamepad array + hid_gamepad_available flag (probed once at init).
  alloc_gamepad finds the lowest free slot, createDevice's a virtual
  gamepad, returns the slot index. free_gamepad disconnects +
  releases. gamepad_update forwards state to the HIDGamepad's
  updateState:. supported_gamepads now reports macos_hid /
  macos_amfi_required depending on probe result.
- cmake/dependencies/macos.cmake: FIND_LIBRARY(IO_KIT_LIBRARY IOKit)
  for IOHIDUserDevice* symbols.
- cmake/compile_definitions/macos.cmake: hid_gamepad.{h,m} added to
  PLATFORM_TARGET_FILES, input.cpp -> input.mm, IO_KIT_LIBRARY linked.
- cmake/dependencies/ffmpeg.cmake: stage a small allow-list of FFmpeg
  internal headers (h2645_parse.h, get_bits.h, etc.) into the dist
  include tree at configure time. src/cbs.cpp uses libavcodec internals
  that `make install` doesn't export; surfacing them inline avoids the
  alternative of adding the FFmpeg source tree to the include path
  wholesale (which collides with libc++'s "thread.h" and friends).

What this does not do:
- Rumble / haptic feedback (Sunshine's feedback_queue_t is accepted but
  not forwarded — virtual HID has no force-feedback motor to drive).
- DualSense touchpad, gyro, adaptive triggers, LED.
- Battery state reporting.
These can be added later under the same HIDGamepad class if needed.

Verified locally: hid_gamepad.m compiles, _OBJC_CLASS_$_HIDGamepad is
linked into Sunshine.app, the AMFI-disabled probe runs at startup and
emits the right instruction line for users not yet on the bypass.
Functional end-to-end test (gamepad events from Moonlight client
actually reaching a game) requires AMFI bypass + reboot.

Lumen attribution: Lumen is MIT-licensed; this port preserves the
underlying design and copies the HID report descriptor verbatim.

Author: Nottlespike

cmake/compile_definitions/macos.cmake

@@ -35,6 +35,7 @@ list(APPEND SUNSHINE_EXTERNAL_LIBRARIES
         ${CORE_MEDIA_LIBRARY}
         ${CORE_VIDEO_LIBRARY}
         ${FOUNDATION_LIBRARY}
+        ${IO_KIT_LIBRARY}
         ${SCREEN_CAPTURE_KIT_LIBRARY}
         ${VIDEO_TOOLBOX_LIBRARY})
 
@@ -47,7 +48,9 @@ set(PLATFORM_TARGET_FILES
         "${CMAKE_SOURCE_DIR}/src/platform/macos/av_audio.mm"
         "${CMAKE_SOURCE_DIR}/src/platform/macos/av_img_t.h"
         "${CMAKE_SOURCE_DIR}/src/platform/macos/display.mm"
-        "${CMAKE_SOURCE_DIR}/src/platform/macos/input.cpp"
+        "${CMAKE_SOURCE_DIR}/src/platform/macos/hid_gamepad.h"
+        "${CMAKE_SOURCE_DIR}/src/platform/macos/hid_gamepad.m"
+        "${CMAKE_SOURCE_DIR}/src/platform/macos/input.mm"
         "${CMAKE_SOURCE_DIR}/src/platform/macos/microphone.mm"
         "${CMAKE_SOURCE_DIR}/src/platform/macos/misc.mm"
         "${CMAKE_SOURCE_DIR}/src/platform/macos/misc.h"

cmake/dependencies/ffmpeg.cmake

@@ -173,3 +173,58 @@ else()
 endif()
 
 set(FFMPEG_INCLUDE_DIRS "${FFMPEG_PREPARED_BINARIES}/include")
+
+# Sunshine's src/cbs.cpp uses libavcodec's INTERNAL headers (cbs_h264.h,
+# cbs_h2645.h, h2645_parse.h, etc.) which FFmpeg's `make install` does
+# not export. Stage the needed internal headers into the dist include
+# tree alongside the public ones. Done at configure time so subsequent
+# rebuilds don't pay the cost. Limited to a known-good list so we don't
+# shadow system headers (FFmpeg has its own "thread.h", "internal.h",
+# etc. that collide with libc++ when the entire source tree is on the
+# include path).
+get_filename_component(_FFMPEG_BINARY_PARENT "${FFMPEG_PREPARED_BINARIES}" DIRECTORY)
+set(_FFMPEG_SOURCE_CANDIDATES
+    "${_FFMPEG_BINARY_PARENT}/FFmpeg/FFmpeg"
+    "${CMAKE_SOURCE_DIR}/third-party/build-deps/build-prores-vt/FFmpeg/FFmpeg"
+)
+foreach(_candidate ${_FFMPEG_SOURCE_CANDIDATES})
+    if(EXISTS "${_candidate}/libavcodec/h2645_parse.h")
+        set(_FFMPEG_INTERNAL_HEADERS
+            libavcodec/h2645_parse.h
+            libavcodec/h2645_sei.h
+            libavcodec/h264_sei.h
+            libavcodec/hevc/sei.h
+            libavcodec/sei.h
+            libavcodec/cbs.h
+            libavcodec/cbs_internal.h
+            libavcodec/cbs_sei.h
+            libavcodec/get_bits.h
+            libavcodec/golomb.h
+            libavcodec/mathops.h
+            libavcodec/mpegutils.h
+            libavcodec/vlc.h
+            libavutil/attributes_internal.h
+            libavutil/internal.h
+            libavutil/thread.h
+            libavutil/timer.h
+            libavutil/reverse.h
+            libavutil/libm.h
+            libavutil/cpu_internal.h
+        )
+        foreach(_hdr ${_FFMPEG_INTERNAL_HEADERS})
+            if(EXISTS "${_candidate}/${_hdr}" AND NOT EXISTS "${FFMPEG_PREPARED_BINARIES}/include/${_hdr}")
+                get_filename_component(_hdr_dir "${FFMPEG_PREPARED_BINARIES}/include/${_hdr}" DIRECTORY)
+                file(MAKE_DIRECTORY "${_hdr_dir}")
+                configure_file("${_candidate}/${_hdr}" "${FFMPEG_PREPARED_BINARIES}/include/${_hdr}" COPYONLY)
+            endif()
+        endforeach()
+        # ffbuild/config.h is needed by libavutil/internal.h. Stage it
+        # at the include-path root so the relative #include "config.h"
+        # from mathops.h finds it.
+        if(EXISTS "${_candidate}/ffbuild/config.h" AND NOT EXISTS "${FFMPEG_PREPARED_BINARIES}/include/config.h")
+            configure_file("${_candidate}/ffbuild/config.h" "${FFMPEG_PREPARED_BINARIES}/include/config.h" COPYONLY)
+        endif()
+        message(STATUS "Sunshine cbs.cpp: staged FFmpeg internal headers from ${_candidate}")
+        break()
+    endif()
+endforeach()

cmake/dependencies/macos.cmake

@@ -9,6 +9,12 @@ FIND_LIBRARY(CORE_AUDIO_LIBRARY CoreAudio)
 FIND_LIBRARY(CORE_MEDIA_LIBRARY CoreMedia)
 FIND_LIBRARY(CORE_VIDEO_LIBRARY CoreVideo)
 FIND_LIBRARY(FOUNDATION_LIBRARY Foundation)
+# IOKit is needed for IOHIDUserDevice* (virtual gamepad device — hid_gamepad.m).
+# Actually creating devices at runtime requires the user to disable AMFI via
+# `nvram boot-args="amfi_get_out_of_my_way=1"`, but the symbols themselves
+# are unconditionally present and the host alloc_gamepad path probes
+# availability before relying on them.
+FIND_LIBRARY(IO_KIT_LIBRARY IOKit)
 FIND_LIBRARY(VIDEO_TOOLBOX_LIBRARY VideoToolbox)
 # ScreenCaptureKit is the modern (macOS 12.3+) replacement for the
 # deprecated AVCaptureScreenInput-based capture path. Sunshine's

src/platform/macos/hid_gamepad.h

@@ -0,0 +1,72 @@
+/**
+ * @file src/platform/macos/hid_gamepad.h
+ * @brief Virtual HID gamepad via IOHIDUserDevice for macOS.
+ * @details Creates a system-wide virtual gamepad that macOS Game Controller
+ *          framework recognizes. Requires SIP to be disabled.
+ */
+#pragma once
+
+#import <Foundation/Foundation.h>
+#import <IOKit/hidsystem/IOHIDUserDevice.h>
+
+/**
+ * HID report sent to IOHIDUserDevice. Packed to exactly 14 bytes.
+ * Matches the HID report descriptor defined in hid_gamepad.m.
+ */
+typedef struct __attribute__((packed)) {
+    uint8_t  reportId;       // Always 0x01
+    uint16_t buttons;        // 16 button bits
+    uint8_t  hatSwitch;      // D-pad hat switch (0-7 = directions, 8 = neutral)
+    uint8_t  leftTrigger;    // 0-255
+    uint8_t  rightTrigger;   // 0-255
+    int16_t  leftStickX;     // -32768 to 32767
+    int16_t  leftStickY;     // -32768 to 32767
+    int16_t  rightStickX;    // -32768 to 32767
+    int16_t  rightStickY;    // -32768 to 32767
+} HIDGamepadReport;
+
+@interface HIDGamepad : NSObject
+
+@property (nonatomic, assign) int gamepadIndex;
+@property (nonatomic, assign) BOOL isConnected;
+@property (nonatomic, assign) IOHIDUserDeviceRef hidDevice;
+@property (nonatomic, strong) dispatch_queue_t hidQueue;
+
+/**
+ * Probes whether IOHIDUserDevice virtual gamepads can be created.
+ * Returns NO when SIP is enabled (device creation fails).
+ */
++ (BOOL)isAvailable;
+
+- (instancetype)initWithIndex:(int)index;
+
+/**
+ * Creates the IOHIDUserDevice and sends an initial neutral-state report.
+ * @return YES on success, NO on failure.
+ */
+- (BOOL)createDevice;
+
+/**
+ * Maps Sunshine's gamepad state to an HID report and sends it.
+ * @param buttons  Sunshine's 32-bit buttonFlags (only lower 16 bits + HOME used)
+ * @param lsX      Left stick X (-32768..32767)
+ * @param lsY      Left stick Y (-32768..32767)
+ * @param rsX      Right stick X (-32768..32767)
+ * @param rsY      Right stick Y (-32768..32767)
+ * @param lt       Left trigger (0..255)
+ * @param rt       Right trigger (0..255)
+ */
+- (void)updateState:(uint32_t)buttons
+         leftStickX:(int16_t)lsX
+         leftStickY:(int16_t)lsY
+        rightStickX:(int16_t)rsX
+        rightStickY:(int16_t)rsY
+        leftTrigger:(uint8_t)lt
+       rightTrigger:(uint8_t)rt;
+
+/**
+ * Destroys the IOHIDUserDevice and cleans up resources.
+ */
+- (void)disconnect;
+
+@end