Using Metalfx Frame Interpolation

---
name: using-metalfx-frame-interpolation
description: ALWAYS use to add MetalFX frame interpolation with a dedicated PresentThread for precise dual-frame presentation to a Metal app. Use this skill when the user wants to add frame interpolation, frame generation, double the framerate, or mentions MTLFXFrameInterpolator (Metal 3) or MTL4FXFrameInterpolator (Metal 4). This skill assumes temporal upscaling is already integrated (use using-metalfx-temporal-upscaler first if not). Also trigger when the user says "add frame gen", "120fps", "interpolate frames", or wants smoother motion.
---

# Adding MetalFX Frame Interpolation to a Metal App

This skill adds MetalFX frame interpolation to a Metal app that already has a MetalFX temporal scaler integrated. The interpolator generates intermediate frames between real rendered frames, effectively doubling the display framerate (e.g., 60fps render → 120fps display).

Two API variants exist:
- **Metal 3** — `MTLFXFrameInterpolator` (macOS 15.0+ / iOS 18.0+)
- **Metal 4** — `MTL4FXFrameInterpolator` (macOS 26.0+ / iOS 26.0+), which inherits from the shared `MTLFXFrameInterpolatorBase` protocol

All per-frame properties are identical across both APIs (they live on `MTLFXFrameInterpolatorBase`). The differences are the creation call, the command buffer type used for encoding, and the support check — see the notes below.

**Prerequisite:** The app must already have MetalFX temporal upscaling working. If not, use the `using-metalfx-temporal-upscaler` skill first.

## Abstraction Strategy

Before starting integration, check if the engine already has a high-level abstraction for frame interpolation (e.g., from DLSS Frame Generation, FSR Frame Gen). If it does, integrate MetalFX through the existing abstraction — follow the same execution paths wherever the APIs are compatible. This makes debugging easier and minimizes the chance for bugs. Only diverge from the existing patterns where MetalFX API differences require it.

If no existing frame interpolation abstraction exists, ask the developer: introduce a minimal abstraction layer (Recommended — cleaner, easier to maintain and debug), or implement MetalFX directly in the source without abstractions (faster, but harder to extend later)?

**Important:** When bridging a row-vector matrix library (DirectXMath for example) to Metal's column-vector simd::float4x4, the matrix must be transposed