METAL: Route texture load through video thread when threaded video active

The Metal driver had a narrow threading issue when used with the
threaded video wrapper.  Unlike the other graphics APIs where
both load and unload have races, Metal's case is specifically
about the shared blit command buffer used during mipmapped
texture creation.

The race
========

When metal_load_texture is called with a TEXTURE_FILTER_MIPMAP_*
filter, the execution path reaches:

  - [self newTexture:image mipmapped:YES] in metal_renderer.m
  - which creates an MTLTexture (thread-safe on MTLDevice)
  - calls replaceRegion: (thread-safe)
  - accesses self.blitCommandBuffer (a lazily-created
    MTLCommandBuffer stored on the shared Context instance)
  - encodes mipmap generation via [cb blitCommandEncoder]

MTLCommandBuffer and MTLCommandEncoder are documented as
single-thread-only.  The blit command buffer is committed and
nulled at frame end, on the video thread:

  - (void)end { ... [_blitCommandBuffer commit];
                    _blitCommandBuffer = nil; ... }

If the main thread calls metal_load_texture mid-frame and
encodes mipmap commands on the same blit command buffer that
the video thread is about to commit, this is undefined
behaviour per Apple's Metal threading rules.

Other Metal paths are already safe
==================================

Most of the Metal driver operations are fine:

  - [_device newTextureWithDescriptor:] is thread-safe
  - [texture replaceRegion:] is thread-safe and synchronous
  - metal_unload_texture releases an ARC-retained handle; Metal
    command buffers retain their referenced resources, so the
    underlying MTLTexture stays alive until the GPU is done.
    No cross-thread race on unload (unlike D3D12/Vulkan where
    command buffers don't refcount resources).

The only remaining race is the blit command buffer sharing
during mipmapped load.

The fix
=======

Route metal_load_texture through video_thread_texture_handle
when threaded video is active, matching the pattern established
in the D3D10/11/12 and Vulkan patches.  This serialises all
Context.blitCommandBuffer access on the video thread.

Implementation:

- Split metal_load_texture into an internal function that does
  the actual texture creation, and an outer function that
  dispatches.

- metal_texture_cmd_t carries video_data (as void* to avoid
  ARC issues with Obj-C refs in C structs), image, filter_type,
  and handle (output).

- Handle is passed back via cmd->handle rather than the int
  return channel of custom_command_method_t to avoid truncation
  on 64-bit Apple platforms.

- The dispatch happens unconditionally for any threaded load,
  not just mipmapped ones -- consistent with other drivers and
  avoids branching on filter type.

- metal_unload_texture is left unchanged (ARC refcounting is
  sufficient).

Depends on: 8d55232 (VIDEO/THREAD: barrier + wrapper hardening),
which hardens video_thread_texture_handle to be safe when the
wrapper is inactive.

Cost: texture load now blocks briefly while the video thread
processes the dispatched command.  Texture loads happen during
menu navigation, not frame-critical paths, so latency is
imperceptible.

No behavioural change on non-threaded video.

Author: LibretroAdmin

gfx/drivers/metal.m

@@ -49,6 +49,9 @@
 
 #include "../font_driver.h"
 #include "../video_driver.h"
+#ifdef HAVE_THREADS
+#include "../video_thread_wrapper.h"
+#endif
 
 #include "../common/metal_common.h"
 
@@ -2568,8 +2571,31 @@ static bool metal_read_viewport(void *data, uint8_t *buffer, bool is_idle)
    return [md.frameView readViewport:buffer isIdle:is_idle];
 }
 
-static uintptr_t metal_load_texture(void *video_data, void *data,
-      bool threaded, enum texture_filter_type filter_type)
+#ifdef HAVE_THREADS
+typedef struct
+{
+   void                         *video_data;  /* unretained MetalDriver * */
+   struct texture_image         *image;
+   enum texture_filter_type      filter_type;
+   uintptr_t                     handle;
+} metal_texture_cmd_t;
+#endif
+
+/* Inner load function -- performs the actual texture creation.
+ * Must run on the same thread that owns the Metal context's
+ * blit command buffer (the video thread when threaded video is
+ * active, otherwise the main thread).
+ *
+ * Metal's blit command buffer is lazily created on first use
+ * and committed during frame end.  It is stored on the shared
+ * Context instance, not thread-local.  Mipmapped texture loads
+ * encode mipmap-generation commands into this buffer via a
+ * BlitCommandEncoder -- and MTLCommandBuffer / MTLCommandEncoder
+ * are explicitly documented as single-thread-only.  Concurrent
+ * access from the main thread (mid-load) and the video thread
+ * (mid-frame-end commit) is undefined behaviour. */
+static uintptr_t metal_load_texture_internal(void *video_data, void *data,
+      enum texture_filter_type filter_type)
 {
    MetalDriver           *md  = (__bridge MetalDriver *)video_data;
    struct texture_image *img  = (struct texture_image *)data;
@@ -2581,11 +2607,56 @@ static uintptr_t metal_load_texture(void *video_data, void *data,
    return (uintptr_t)(__bridge_retained void *)(t);
 }
 
+#ifdef HAVE_THREADS
+/* Wrap function invoked on the video thread via
+ * CMD_CUSTOM_COMMAND.  Writes the handle to cmd->handle rather
+ * than the int return channel to avoid truncation on 64-bit
+ * Apple platforms where uintptr_t is 64 bits. */
+static int metal_texture_load_wrap(void *data)
+{
+   metal_texture_cmd_t *cmd = (metal_texture_cmd_t*)data;
+   cmd->handle = metal_load_texture_internal(
+         cmd->video_data, cmd->image, cmd->filter_type);
+   return 0;
+}
+#endif
+
+static uintptr_t metal_load_texture(void *video_data, void *data,
+      bool threaded, enum texture_filter_type filter_type)
+{
+#ifdef HAVE_THREADS
+   /* When threaded video is active, dispatch to the video
+    * thread so Context.blitCommandBuffer access is serialised
+    * with the video thread's frame-end commit.  This is only
+    * required for mipmapped filters (which encode into the
+    * blit buffer), but we dispatch unconditionally for
+    * consistency and simplicity. */
+   if (threaded)
+   {
+      metal_texture_cmd_t cmd;
+      cmd.video_data  = video_data;
+      cmd.image       = (struct texture_image *)data;
+      cmd.filter_type = filter_type;
+      cmd.handle      = 0;
+      video_thread_texture_handle(&cmd, metal_texture_load_wrap);
+      return cmd.handle;
+   }
+#endif
+
+   return metal_load_texture_internal(video_data, data, filter_type);
+}
+
 static void metal_unload_texture(void *data,
       bool threaded, uintptr_t handle)
 {
    if (!handle)
       return;
+   /* Metal command buffers retain their referenced resources,
+    * so ARC-releasing the handle here does not free the
+    * underlying MTLTexture if the video thread's command
+    * buffer is still using it -- the Metal runtime refcounts
+    * resources across CPU and GPU.  No cross-thread
+    * serialisation needed for unload. */
    Texture *t = (__bridge_transfer Texture *)(void *)handle;
    t = nil;
 }