Use metal-cpp for public facing contract

[bghgary]

This pull request introduces several improvements and fixes across build scripts, test configuration, and platform-specific initialization code. The most significant changes include restructuring how Metal layers are passed to the app context on Apple platforms, modernizing the test configuration format, and cleaning up build system logic for better maintainability and correctness.

Apple platform improvements:

• Updated Metal layer initialization for iOS, macOS, and visionOS to use (__bridge CA::MetalLayer*) casting when passing the layer to the application context, ensuring correct type usage and better compatibility with Metal APIs (Apps/Playground/iOS/LibNativeBridge.mm, Apps/Playground/macOS/ViewController.mm, Apps/Playground/visionOS/LibNativeBridge.mm) [1] F722f6f4L69R69, [2].
• Adjusted Apple build logic: removed redundant explicit Objective-C ARC (Automatic Reference Counting) Xcode property settings and replaced them with a call to enable_objc_arc(), simplifying ARC management (Apps/Playground/CMakeLists.txt) [1] [2] [3].
• Fixed the Metal device creation in unit tests to use the correct function (MTL::CreateSystemDefaultDevice()) and removed a redundant Metal include (Apps/UnitTests/Source/App.Apple.mm) [1] [2].

Test configuration modernization:

• Refactored Apps/Playground/Scripts/config.json to replace the single comment field with a comments object, allowing for per-graphics-API comments and adding more detailed test exclusion reasons. Also added new Metal exclusions where appropriate [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13].

Build and CI script fixes:

• Fixed Windows CI script to use the correct directory for running validation tests by combining two cd commands into one (.github/jobs/win32.yml).
• Cleaned up CMake build logic by removing unnecessary or misplaced library inclusions and ensuring correct file extensions for macOS source files (Apps/Playground/CMakeLists.txt) [1] [2] [3] [4] [5].

Platform-specific exit code handling:

• Changed the application exit code on Windows and X11 to always return 0 instead of a test utility error code, standardizing process termination behavior (Apps/Playground/Win32/App.cpp, Apps/Playground/X11/App.cpp) [1] [2].

Header and import improvements:

• Switched from #import to #include for C++ headers and properly separated Objective-C and C++ imports in the macOS ViewController, improving header hygiene (Apps/Playground/macOS/ViewController.mm).

[Copilot]

Pull request overview

This PR migrates the Apple Metal “public-facing contract” from Objective‑C Metal types (id<MTL*>, MTKView*, CAMetalLayer*) to metal-cpp types (MTL::*, CA::MetalLayer*) and adjusts build/install wiring and platform glue accordingly.

Changes:

• Introduces a generated metal-cpp dependency (single-header + implementation TU) and links it into Graphics/device-facing targets on Apple.
• Updates Metal-facing typedefs (RendererType.h, Platform.h) and several Apple call sites to use MTL::* / CA::* types.
• Refactors TestUtils platform implementations to store WindowT directly (removing the prior ImplData indirection) and updates Playground/CI plumbing.

Reviewed changes

Copilot reviewed 42 out of 44 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
Plugins/TestUtils/Source/TestUtils_macOS.mm	Adds macOS-specific TestUtils implementation (window ops, output dir, framebuffer postprocess).
Plugins/TestUtils/Source/TestUtils_iOS.mm	Adds iOS-specific TestUtils stubs for unimplemented behaviors.
Plugins/TestUtils/Source/TestUtils_WinRT.cpp	Updates WinRT TestUtils initialization and exit behavior.
Plugins/TestUtils/Source/TestUtils_Win32.cpp	Updates Win32 TestUtils to use m_window directly and quick-exit on failure.
Plugins/TestUtils/Source/TestUtils_Unix.cpp	Updates X11 TestUtils to use m_window and quick-exit on failure.
Plugins/TestUtils/Source/TestUtils_Android.cpp	Aligns Android TestUtils with new internal API shape.
Plugins/TestUtils/Source/TestUtilsImplData.h	Removes the ImplData wrapper used to store WindowT.
Plugins/TestUtils/Source/TestUtils.h	Changes TestUtils instance creation to pass WindowT directly into the JS wrapper.
Plugins/TestUtils/Source/TestUtils.cpp	Wires framebuffer post-processing and re-homes plugin Initialize.
Plugins/TestUtils/Source/Apple/TestUtilsImpl.mm	Removes previous Apple combined implementation.
Plugins/TestUtils/Include/Babylon/Plugins/TestUtils.h	Removes exported errorCode and keeps Initialize API.
Plugins/TestUtils/CMakeLists.txt	Switches to per-platform TestUtils source file selection and enables ObjC ARC on Apple.
Plugins/ShaderCache/CMakeLists.txt	Adjusts ShaderCacheInternal interface linkage behavior.
Plugins/NativeTracing/CMakeLists.txt	Replaces manual Xcode ARC property with enable_objc_arc(...).
Plugins/NativeOptimizations/CMakeLists.txt	Replaces manual Xcode ARC property with enable_objc_arc(...).
Plugins/NativeEngine/CMakeLists.txt	Ensures ShaderCache is explicitly linked when enabled.
Plugins/NativeCamera/CMakeLists.txt	Enables ObjC ARC and adjusts Apple build flags/unity build behavior.
Plugins/ExternalTexture/Source/ExternalTexture_Metal.cpp	Migrates Metal texture handling to metal-cpp (MTL::Texture*, NS::SharedPtr).
Plugins/ExternalTexture/CMakeLists.txt	Uses .cpp implementation file naming for ExternalTexture sources.
Install/Install.cmake	Adds install rules for metal-cpp and reorders/expands install targets.
Dependencies/xr/CMakeLists.txt	Replaces manual Xcode ARC property with enable_objc_arc(...).
Dependencies/CMakeLists.txt	Adds FetchContent for metal-cpp and generates single-header + implementation source.
Core/Graphics/Source/DeviceImpl_visionOS.mm	Simplifies device pixel ratio function signature/body.
Core/Graphics/Source/DeviceImpl_macOS.mm	Updates macOS pixel ratio logic and uses Metal layer scale.
Core/Graphics/Source/DeviceImpl_iOS.mm	Updates iOS pixel ratio logic and uses Metal layer scale.
Core/Graphics/Source/DeviceImpl_Metal.mm	Returns platform info as metal-cpp MTL::* pointers.
Core/Graphics/Include/RendererType/Metal/Babylon/Graphics/RendererType.h	Changes Metal renderer typedefs to metal-cpp pointers and includes Metal.hpp.
Core/Graphics/Include/Platform/visionOS/Babylon/Graphics/Platform.h	Switches WindowT to CA::MetalLayer* and includes Metal.hpp.
Core/Graphics/Include/Platform/macOS/Babylon/Graphics/Platform.h	Switches WindowT to CA::MetalLayer* and includes Metal.hpp.
Core/Graphics/Include/Platform/iOS/Babylon/Graphics/Platform.h	Switches WindowT to CA::MetalLayer* and includes Metal.hpp.
Core/Graphics/CMakeLists.txt	Links metal-cpp on Apple and refactors Graphics/GraphicsDevice* wiring.
CMakeLists.txt	Updates CMakeExtensions revision and adds FetchContent declaration for metal-cpp zip.
Apps/UnitTests/Source/Utils.Metal.mm	Migrates test texture creation/destruction to metal-cpp API.
Apps/UnitTests/Source/App.Apple.mm	Creates default Metal device via metal-cpp.
Apps/Playground/visionOS/LibNativeBridge.mm	Updates AppContext construction to pass metal-cpp window type.
Apps/Playground/macOS/main.mm	Adds a macOS Objective-C++ entrypoint enabling debug trace.
Apps/Playground/macOS/ViewController.mm	Passes Metal layer into AppContext using new window type.
Apps/Playground/iOS/LibNativeBridge.mm	Passes Metal layer into AppContext using new window type.
Apps/Playground/X11/App.cpp	Removes dependency on TestUtils::errorCode and always returns 0 on normal exit.
Apps/Playground/Win32/App.cpp	Removes PostQuitMessage(errorCode) dependency on removed errorCode.
Apps/Playground/Scripts/validation_native.js	No functional change (formatting-only newline change).
Apps/Playground/Scripts/config.json	Replaces single comment with per-API comments and extends exclusions for Metal.
Apps/Playground/CMakeLists.txt	Adjusts Apple entrypoint extension, ARC enabling, and link ordering.
.github/jobs/win32.yml	Simplifies path changes for validation test invocation.

Comments suppressed due to low confidence (2)

Core/Graphics/Source/DeviceImpl_iOS.mm:27

• Same issue as macOS: WindowT is CA::MetalLayer* but this casts to CAMetalLayer* and reads an ObjC property. Use the metal-cpp API (window->contentsScale()) or an explicit reinterpret_cast if bridging is required.

        float scale = static_cast<float>(((CAMetalLayer*)window).contentsScale);
        if (std::isinf(scale) || scale <= 0)
        {
            scale = UIScreen.mainScreen.scale;
        }

Plugins/ExternalTexture/Source/ExternalTexture_Metal.cpp:295

• RetainPtr is referenced but not defined in this translation unit (and there is no using bringing it into scope). With metal-cpp, the helper is typically NS::RetainPtr(...). As written this looks like a compile error; qualify the call (or replace with an explicit NS::SharedPtr construction) so ownership is clear.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bghgary]

Comments from synchronous review