Implement setPresentationTime for Metal (#9470)

Author: bejado

NEW_RELEASE_NOTES.md

@@ -6,3 +6,5 @@
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
+
+- Support `setPresentationTime` with the Metal backend.

filament/backend/src/metal/MetalDriver.mm

@@ -312,6 +312,8 @@
 }
 
 void MetalDriver::setPresentationTime(int64_t monotonic_clock_ns) {
+    assert_invariant(mContext->currentDrawSwapChain);
+    mContext->currentDrawSwapChain->setPresentationTime(monotonic_clock_ns);
 }
 
 void MetalDriver::endFrame(uint32_t frameId) {

filament/backend/src/metal/MetalHandles.h

@@ -141,6 +141,8 @@ class MetalSwapChain : public HwSwapChain {
     // FrameScheduledCallback.
     void present();
 
+    void setPresentationTime(int64_t timeNs) { presentationTimeNs = timeNs; }
+
     NSUInteger getSurfaceWidth() const;
     NSUInteger getSurfaceHeight() const;
     NSUInteger getSampleCount() const;
@@ -159,7 +161,7 @@ class MetalSwapChain : public HwSwapChain {
     bool isCaMetalLayer() const { return type == SwapChainType::CAMETALLAYER; }
     bool isHeadless() const { return type == SwapChainType::HEADLESS; }
 
-    void scheduleFrameScheduledCallback();
+    void scheduleFrameScheduledCallback(int64_t presentationTimeNs);
     void scheduleFrameCompletedCallback();
 
     MetalAttachment acquireBaseDrawable();
@@ -192,6 +194,11 @@ class MetalSwapChain : public HwSwapChain {
 
     int64_t abandonedUntilFrame = -1;
 
+    // If zero, the next presentation should happen as soon as possible.
+    // Otherwise, this is the timestamp when the present should happen.
+    // Resets to 0 after the present.
+    int64_t presentationTimeNs = 0;
+
     // These fields store a callback to notify the client that a frame is ready for presentation. If
     // !frameScheduled.callback, then the Metal backend automatically calls presentDrawable when the
     // frame is committed. Otherwise, the Metal backend will not automatically present the frame.

filament/backend/src/metal/MetalHandles.mm

@@ -325,11 +325,19 @@ static inline MTLTextureUsage getMetalTextureUsage(TextureUsage usage) {
     if (frameCompleted.callback) {
         scheduleFrameCompletedCallback();
     }
+    const auto timeNs = presentationTimeNs;
+    presentationTimeNs = 0;
     if (drawable) {
         if (frameScheduled.callback) {
-            scheduleFrameScheduledCallback();
+            scheduleFrameScheduledCallback(timeNs);
         } else  {
-            [getPendingCommandBuffer(&context) presentDrawable:drawable];
+            if (presentationTimeNs) {
+                const CFTimeInterval timeSeconds =
+                        (CFTimeInterval) presentationTimeNs / 1000000000.0;
+                [getPendingCommandBuffer(&context) presentDrawable:drawable atTime:timeSeconds];
+            } else {
+                [getPendingCommandBuffer(&context) presentDrawable:drawable];
+            }
         }
     }
 }
@@ -341,15 +349,22 @@ static inline MTLTextureUsage getMetalTextureUsage(TextureUsage usage) {
     PresentDrawableData& operator=(const PresentDrawableData&) = delete;
 
     static PresentDrawableData* create(id<CAMetalDrawable> drawable,
-            std::shared_ptr<std::mutex> drawableMutex, MetalDriver* driver, uint64_t flags) {
+            std::shared_ptr<std::mutex> drawableMutex, MetalDriver* driver, uint64_t flags,
+            int64_t presentationTimeNs) {
         assert_invariant(drawableMutex);
         assert_invariant(driver);
-        return new PresentDrawableData(drawable, drawableMutex, driver, flags);
+        return new PresentDrawableData(drawable, drawableMutex, driver, flags, presentationTimeNs);
     }
 
     static void maybePresentAndDestroyAsync(PresentDrawableData* that, bool shouldPresent) {
         if (shouldPresent) {
-           [that->mDrawable present];
+            if (that->mPresentationTimeNs) {
+                const CFTimeInterval timeSeconds =
+                        (CFTimeInterval) that->mPresentationTimeNs / 1000000000.0;
+                [that->mDrawable presentAtTime:timeSeconds];
+            } else {
+                [that->mDrawable present];
+            }
         }
 
         if (that->mFlags & SwapChain::CALLBACK_DEFAULT_USE_METAL_COMPLETION_HANDLER) {
@@ -367,8 +382,12 @@ static void maybePresentAndDestroyAsync(PresentDrawableData* that, bool shouldPr
 
 private:
     PresentDrawableData(id<CAMetalDrawable> drawable, std::shared_ptr<std::mutex> drawableMutex,
-            MetalDriver* driver, uint64_t flags)
-        : mDrawable(drawable), mDrawableMutex(drawableMutex), mDriver(driver), mFlags(flags) {}
+            MetalDriver* driver, uint64_t flags, int64_t presentationTimeNs)
+            : mDrawable(drawable),
+              mDrawableMutex(drawableMutex),
+              mDriver(driver),
+              mFlags(flags),
+              mPresentationTimeNs(presentationTimeNs) {}
 
     static void cleanupAndDestroy(PresentDrawableData *that) {
         if (that->mDrawable) {
@@ -384,14 +403,15 @@ static void cleanupAndDestroy(PresentDrawableData *that) {
     std::shared_ptr<std::mutex> mDrawableMutex;
     MetalDriver* mDriver = nullptr;
     uint64_t mFlags = 0;
+    int64_t mPresentationTimeNs = 0;
 };
 
 void presentDrawable(bool presentFrame, void* user) {
     auto* presentDrawableData = static_cast<PresentDrawableData*>(user);
     PresentDrawableData::maybePresentAndDestroyAsync(presentDrawableData, presentFrame);
 }
 
-void MetalSwapChain::scheduleFrameScheduledCallback() {
+void MetalSwapChain::scheduleFrameScheduledCallback(int64_t presentationTimeNs) {
     if (!frameScheduled.callback) {
         return;
     }
@@ -400,8 +420,11 @@ void presentDrawable(bool presentFrame, void* user) {
 
     struct Callback {
         Callback(std::shared_ptr<FrameScheduledCallback> callback, id<CAMetalDrawable> drawable,
-                 std::shared_ptr<std::mutex> drawableMutex, MetalDriver* driver, uint64_t flags)
-            : f(callback), data(PresentDrawableData::create(drawable, drawableMutex, driver, flags)) {}
+                std::shared_ptr<std::mutex> drawableMutex, MetalDriver* driver, uint64_t flags,
+                int64_t presentationTimeNs)
+                : f(callback),
+                  data(PresentDrawableData::create(drawable, drawableMutex, driver, flags,
+                          presentationTimeNs)) {}
         std::shared_ptr<FrameScheduledCallback> f;
         // PresentDrawableData* is destroyed by maybePresentAndDestroyAsync() later.
         std::unique_ptr<PresentDrawableData> data;
@@ -419,7 +442,7 @@ static void func(void* user) {
     uint64_t const flags = frameScheduled.flags;
     ReleasablePointer* callback = [[ReleasablePointer alloc]
             initWithPointer:new Callback(frameScheduled.callback, drawable, layerDrawableMutex,
-                                    context.driver, flags)];
+                                    context.driver, flags, presentationTimeNs)];
 
     backend::CallbackHandler* handler = frameScheduled.handler;
     MetalDriver* driver = context.driver;