Add Metal backend support on Apple platforms

.github/workflows/build.yml

@@ -60,6 +60,107 @@ jobs:
           name: ios_build
           path: ios
 
+  mac_metal:
+    # Compile-only verification of the Metal backend on macOS. Building PAGFullTest covers all
+    # test modules on top of the library itself. Running the Metal tests (PAGFullTest_Metal)
+    # requires the per-backend test infrastructure, which lands in a follow-up PR.
+    runs-on: macos-14
+    steps:
+      - name: Check Out Repo
+        uses: actions/checkout@v4
+
+      - name: Get Third-Party Cache
+        id: third-party-cache
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            third_party
+          key: third-party-mac-metal-${{ hashFiles('DEPS') }}-${{ hashFiles('vendor.json') }}
+          restore-keys: |
+            third-party-mac-metal-
+            third-party-autotest-
+
+      - uses: tecolicom/actions-use-homebrew-tools@v1
+        with:
+          tools: ninja yasm
+
+      - name: Run depsync
+        run: |
+          npm install depsync -g
+          depsync
+        shell: bash
+
+      - name: Build macOS Metal
+        run: |
+          mkdir -p third_party/tgfx/out/cache
+          cmake -G Ninja -DPAG_USE_METAL=ON -DPAG_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug -B build-metal
+          cmake --build build-metal --target PAGFullTest -- -j 12
+
+      - name: Save Third-Party Cache
+        if: ${{ (github.event_name == 'push') && (steps.third-party-cache.outputs.cache-hit != 'true') }}
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            third_party
+          key: third-party-mac-metal-${{ hashFiles('DEPS') }}-${{ hashFiles('vendor.json') }}
+
+  ios_metal:
+    # Compile-only verification of the Metal backend on iOS devices (arm64). The deployment
+    # target is raised to 15.0 automatically by the top-level CMakeLists when Metal is enabled.
+    runs-on: macos-latest
+    steps:
+      - name: Check Out Repo
+        uses: actions/checkout@v4
+
+      - name: Get Third-Party Cache
+        id: third-party-cache
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            third_party
+          key: third-party-ios-metal-${{ hashFiles('DEPS') }}-${{ hashFiles('vendor.json') }}
+          restore-keys: |
+            third-party-ios-metal-
+            third-party-ios-
+
+      - uses: tecolicom/actions-use-homebrew-tools@v1
+        with:
+          tools: ninja yasm
+
+      - name: Install Build Tools
+        run: |
+          chmod +x install_tools.sh
+          ./install_tools.sh
+        shell: bash
+
+      - name: Run depsync
+        run: |
+          npm install depsync -g
+          depsync
+        shell: bash
+
+      - name: Build iOS Metal
+        run: |
+          mkdir -p third_party/tgfx/out/cache
+          cd ios
+          node gen_ios -DPAG_USE_METAL=ON
+          xcodebuild -workspace PAGViewer.xcworkspace -scheme PAGViewer -configuration Release -sdk iphoneos -arch arm64 CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO
+
+      - name: Save Third-Party Cache
+        if: ${{ (github.event_name == 'push') && (steps.third-party-cache.outputs.cache-hit != 'true') }}
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            third_party
+          key: third-party-ios-metal-${{ hashFiles('DEPS') }}-${{ hashFiles('vendor.json') }}
+
+      - name: Job Failed
+        if: ${{ failure() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: ios_metal_build
+          path: ios
+
   android:
     runs-on: ubuntu-latest
     steps:

CMakeLists.txt

@@ -1,4 +1,15 @@
 cmake_minimum_required(VERSION 3.13)
+
+# The iOS toolchain (third_party/vendor_tools/ios.toolchain.cmake) reads DEPLOYMENT_TARGET while
+# configuring the project and derives both the deployment target and the compiler target triple
+# from it. Apple toolchains reject iOS deployment targets below 15.0 (Xcode 26/27 SDKs), and
+# the tgfx Metal backend has its own >= 13.0 floor that 15.0 satisfies, so Metal builds must
+# pre-set the minimum before configuration. This only applies to iOS builds; macOS keeps its own
+# default. Callers can override with -DDEPLOYMENT_TARGET=... explicitly.
+if (PAG_USE_METAL AND NOT DEFINED DEPLOYMENT_TARGET AND PLATFORM MATCHES "^(OS|SIMULATOR)")
+    set(DEPLOYMENT_TARGET "15.0" CACHE STRING "Minimum iOS deployment target" FORCE)
+endif ()
+
 project(PAG)
 
 if (APPLE)
@@ -25,6 +36,10 @@ set(CMAKE_CXX_VISIBILITY_PRESET hidden)
 
 # Options for building libpag
 option(PAG_USE_OPENGL "Allow use of OpenGL as GPU backend" ON)
+option(PAG_USE_METAL "Use Metal as the GPU backend on Apple platforms" OFF)
+option(PAG_USE_VULKAN "Use Vulkan as the GPU backend" OFF)
+option(PAG_USE_D3D12 "Use D3D12 as the GPU backend on Windows" OFF)
+option(PAG_USE_WEBGPU "Use WebGPU as the GPU backend on Web" OFF)
 option(PAG_USE_SWIFTSHADER "Allow build with the SwiftShader library" OFF)
 option(PAG_USE_ANGLE "Allow build with the ANGLE library" OFF)
 option(PAG_USE_QT "Allow build with QT frameworks" OFF)
@@ -87,6 +102,62 @@ if (MACOS AND CLION_IDE AND NOT HasParent)
     option(PAG_BUILD_TESTS "Build libpag tests" ON)
 endif ()
 
+# Non-GL backends (Metal / Vulkan / D3D12 / WebGPU) are mutually exclusive with each other and
+# with OpenGL. If any non-GL backend is enabled, disable OpenGL and all GL-only variants
+# (QT / SwiftShader / ANGLE). This mirrors the mutual-exclusion contract enforced in
+# third_party/tgfx/CMakeLists.txt, and must run BEFORE the existing QT / SwiftShader mutual-
+# exclusion block so the "if (PAG_USE_QT OR PAG_USE_SWIFTSHADER OR PAG_USE_ANGLE) set(PAG_USE_OPENGL ON)"
+# fixup further down does not accidentally re-enable GL.
+#
+# The non-GL backends must not be combined: libpag passes each PAG_USE_* to tgfx unchanged, but
+# tgfx resolves them with its own priority chain (Vulkan > D3D12 > Metal > WebGPU) and silently
+# disables the losers. A combination would leave libpag compiling backend glue (Devices_*.cpp)
+# for a backend tgfx never built, failing at link time with undefined symbols.
+set(PAG_NON_GL_BACKENDS_COUNT 0)
+foreach (backend PAG_USE_METAL PAG_USE_VULKAN PAG_USE_D3D12 PAG_USE_WEBGPU)
+    if (${backend})
+        math(EXPR PAG_NON_GL_BACKENDS_COUNT "${PAG_NON_GL_BACKENDS_COUNT} + 1")
+    endif ()
+endforeach ()
+if (PAG_NON_GL_BACKENDS_COUNT GREATER 1)
+    message(FATAL_ERROR
+            "Only one non-OpenGL backend may be enabled at a time "
+            "(PAG_USE_METAL / PAG_USE_VULKAN / PAG_USE_D3D12 / PAG_USE_WEBGPU).")
+endif ()
+
+if (PAG_USE_METAL OR PAG_USE_VULKAN OR PAG_USE_D3D12 OR PAG_USE_WEBGPU)
+    foreach (gl_variant PAG_USE_OPENGL PAG_USE_QT PAG_USE_SWIFTSHADER PAG_USE_ANGLE)
+        if (${gl_variant})
+            message(WARNING "${gl_variant} is ignored because a non-OpenGL backend is enabled.")
+        endif ()
+    endforeach ()
+    set(PAG_USE_OPENGL OFF)
+    set(PAG_USE_QT OFF)
+    set(PAG_USE_SWIFTSHADER OFF)
+    set(PAG_USE_ANGLE OFF)
+endif ()
+
+# The Metal backend requires iOS 13+ (see the tgfx deployment-target check) and supports the iOS
+# simulator on arm64 only. Raise the deployment target automatically when Metal is selected so
+# `gen_ios -DPAG_USE_METAL=ON` needs no extra flags (as documented in ios/README.md). Without this
+# the toolchain's iOS default (9.0) flows into tgfx and trips its >= 13.0 check. Must run before
+# tgfx is added via add_subdirectory(). Metal also only exists on Apple platforms — reject it
+# elsewhere up front instead of failing later with a pile of undefined symbols.
+if (PAG_USE_METAL AND NOT APPLE)
+    message(FATAL_ERROR "PAG_USE_METAL is only supported on Apple platforms.")
+endif ()
+# The Metal backend supports the iOS simulator on arm64 only.
+if (PAG_USE_METAL AND IOS)
+    set(CMAKE_XCODE_ATTRIBUTE_EXCLUDED_ARCHS[sdk=iphonesimulator*] "x86_64")
+endif ()
+
+if (NOT PAG_USE_OPENGL AND NOT PAG_USE_METAL AND NOT PAG_USE_VULKAN
+        AND NOT PAG_USE_D3D12 AND NOT PAG_USE_WEBGPU)
+    message(FATAL_ERROR
+            "At least one GPU backend must be enabled "
+            "(PAG_USE_OPENGL / PAG_USE_METAL / PAG_USE_VULKAN / PAG_USE_D3D12 / PAG_USE_WEBGPU).")
+endif ()
+
 if (PAG_USE_QT)
     set(PAG_USE_SWIFTSHADER OFF)
     set(PAG_USE_ANGLE OFF)
@@ -120,6 +191,26 @@ if (PAG_USE_QT OR PAG_USE_SWIFTSHADER OR PAG_USE_ANGLE)
     set(PAG_USE_OPENGL ON)
 endif ()
 
+# Expose the selected tgfx backend to libpag sources. The Devices_* implementation files dispatch
+# on this macro to pick the right tgfx backend headers; kept in sync with the TGFX_USE_* variables
+# passed to tgfx further down. libpag defines its own copy instead of relying on tgfx's PRIVATE
+# compile definitions, so tgfx can change its visibility policy without breaking libpag.
+if (PAG_USE_OPENGL)
+    list(APPEND PAG_DEFINES TGFX_USE_OPENGL)
+endif ()
+if (PAG_USE_METAL)
+    list(APPEND PAG_DEFINES TGFX_USE_METAL)
+endif ()
+if (PAG_USE_VULKAN)
+    list(APPEND PAG_DEFINES TGFX_USE_VULKAN)
+endif ()
+if (PAG_USE_D3D12)
+    list(APPEND PAG_DEFINES TGFX_USE_D3D12)
+endif ()
+if (PAG_USE_WEBGPU)
+    list(APPEND PAG_DEFINES TGFX_USE_WEBGPU)
+endif ()
+
 if (PAG_USE_FFAVC)
     set(PAG_USE_LIBAVC OFF)
 endif ()
@@ -201,6 +292,13 @@ file(GLOB_RECURSE SRC_FILES
         src/base/*.*
         src/codec/*.*
         src/rendering/*.*)
+# Devices_Metal.mm is an Objective-C++ file; it only has content under TGFX_USE_METAL. On non-Apple
+# platforms the GCC toolchain lacks the Objective-C++ frontend (`cc1objplus`) and would fail even
+# compiling an empty .mm. Drop it from the source list outside of Apple.
+if (NOT APPLE)
+    list(FILTER SRC_FILES EXCLUDE REGEX "src/rendering/gpu/Devices_Metal\\.mm$")
+    list(FILTER SRC_FILES EXCLUDE REGEX "src/base/utils/TGFXCast_Metal\\.mm$")
+endif ()
 list(APPEND PAG_FILES ${SRC_FILES})
 
 if (PAG_BUILD_PAGX)
@@ -465,8 +563,7 @@ elseif (IOS)
             find_library(OpenGLES_LIBS OpenGLES REQUIRED)
             list(APPEND PAG_SHARED_LIBS ${OpenGLES_LIBS})
             list(APPEND PAG_DEFINES GLES_SILENCE_DEPRECATION)
-        else ()
-            # Uses Metal instead.
+        elseif (PAG_USE_METAL)
             find_library(Metal_LIBS Metal REQUIRED)
             list(APPEND PAG_SHARED_LIBS ${Metal_LIBS})
         endif ()
@@ -508,8 +605,7 @@ elseif (MACOS)
             find_library(OpenGL_LIBS OpenGL REQUIRED)
             list(APPEND PAG_SHARED_LIBS ${OpenGL_LIBS})
             list(APPEND PAG_DEFINES GL_SILENCE_DEPRECATION)
-        else ()
-            # Uses Metal instead.
+        elseif (PAG_USE_METAL)
             find_library(Metal_LIBS Metal REQUIRED)
             list(APPEND PAG_SHARED_LIBS ${Metal_LIBS})
         endif ()
@@ -665,6 +761,10 @@ elseif (HAS_CUSTOM_TGFX_DIR)
     message("TGFX_DIR: ${TGFX_DIR}")
     list(APPEND PAG_INCLUDES ${TGFX_DIR}/include)
     set(TGFX_USE_OPENGL ${PAG_USE_OPENGL})
+    set(TGFX_USE_METAL ${PAG_USE_METAL})
+    set(TGFX_USE_VULKAN ${PAG_USE_VULKAN})
+    set(TGFX_USE_D3D12 ${PAG_USE_D3D12})
+    set(TGFX_USE_WEBGPU ${PAG_USE_WEBGPU})
     set(TGFX_USE_QT ${PAG_USE_QT})
     set(TGFX_USE_SWIFTSHADER ${PAG_USE_SWIFTSHADER})
     set(TGFX_USE_ANGLE ${PAG_USE_ANGLE})
@@ -689,6 +789,10 @@ else ()
     if (EXISTS ${TGFX_CACHE_DIR})
         message("TGFX_CACHE_DIR: ${TGFX_CACHE_DIR}")
         list(APPEND TGFX_OPTIONS "-DTGFX_USE_OPENGL=${PAG_USE_OPENGL}")
+        list(APPEND TGFX_OPTIONS "-DTGFX_USE_METAL=${PAG_USE_METAL}")
+        list(APPEND TGFX_OPTIONS "-DTGFX_USE_VULKAN=${PAG_USE_VULKAN}")
+        list(APPEND TGFX_OPTIONS "-DTGFX_USE_D3D12=${PAG_USE_D3D12}")
+        list(APPEND TGFX_OPTIONS "-DTGFX_USE_WEBGPU=${PAG_USE_WEBGPU}")
         list(APPEND TGFX_OPTIONS "-DTGFX_USE_QT=${PAG_USE_QT}")
         list(APPEND TGFX_OPTIONS "-DTGFX_USE_SWIFTSHADER=${PAG_USE_SWIFTSHADER}")
         list(APPEND TGFX_OPTIONS "-DTGFX_USE_ANGLE=${PAG_USE_ANGLE}")
@@ -723,6 +827,10 @@ else ()
     else ()
         message("TGFX_DIR: ${TGFX_DIR}")
         set(TGFX_USE_OPENGL ${PAG_USE_OPENGL})
+        set(TGFX_USE_METAL ${PAG_USE_METAL})
+        set(TGFX_USE_VULKAN ${PAG_USE_VULKAN})
+        set(TGFX_USE_D3D12 ${PAG_USE_D3D12})
+        set(TGFX_USE_WEBGPU ${PAG_USE_WEBGPU})
         set(TGFX_USE_QT ${PAG_USE_QT})
         set(TGFX_USE_SWIFTSHADER ${PAG_USE_SWIFTSHADER})
         set(TGFX_USE_ANGLE ${PAG_USE_ANGLE})

include/pag/c/pag_backend_semaphore.h

@@ -33,4 +33,18 @@ PAG_EXPORT void pag_backend_semaphore_init_gl(pag_backend_semaphore* semaphore,
 
 PAG_EXPORT void* pag_backend_semaphore_get_gl_sync(pag_backend_semaphore* semaphore);
 
+/**
+ * Initialize the semaphore with a Metal id<MTLEvent> and a timeline signal value. Passing a
+ * null event leaves the semaphore uninitialized.
+ */
+PAG_EXPORT void pag_backend_semaphore_init_metal(pag_backend_semaphore* semaphore,
+                                                 void* mtlEvent, unsigned long long value);
+
+/**
+ * Copies the underlying id<MTLEvent> handle and timeline value into eventInfo. Returns false and
+ * leaves eventInfo untouched if the semaphore was not initialized for the Metal backend.
+ */
+PAG_EXPORT bool pag_backend_semaphore_get_mtl_event(pag_backend_semaphore* semaphore,
+                                                    pag_mtl_event_info* eventInfo);
+
 PAG_C_PLUS_PLUS_END_GUARD

include/pag/c/pag_backend_texture.h

@@ -29,6 +29,14 @@ PAG_C_PLUS_PLUS_BEGIN_GUARD
 PAG_EXPORT pag_backend_texture* pag_backend_texture_create_from_gl_texture_info(
     pag_gl_texture_info textureInfo, int width, int height);
 
+/**
+ * Creates a new pag_backend_texture from a Metal id<MTLTexture>. Release it by pag_release.
+ * The MTLTexture pointer inside textureInfo is stored as an opaque handle; libpag will not
+ * release it.
+ */
+PAG_EXPORT pag_backend_texture* pag_backend_texture_create_from_mtl_texture_info(
+    pag_mtl_texture_info textureInfo, int width, int height);
+
 PAG_EXPORT bool pag_backend_texture_get_gl_texture_info(pag_backend_texture* texture,
                                                      pag_gl_texture_info* textureInfo);
 

include/pag/c/pag_types.h

@@ -105,6 +105,12 @@ typedef struct pag_mtl_texture_info {
   void* texture = nullptr;
 } pag_mtl_texture_info;
 
+// Sync info for an id<MTLEvent>. Always timeline-style (event pointer + signal value).
+typedef struct pag_mtl_event_info {
+  void* event = nullptr;
+  unsigned long long value = 0;
+} pag_mtl_event_info;
+
 typedef struct pag_point {
   float x;
   float y;