Add warnings (hopefully temporary) about macOS deadlock.

android/filament-android/src/main/java/com/google/android/filament/Engine.java

@@ -609,6 +609,9 @@ public class Engine {
      * all commands to this point are executed. Note that this doesn't guarantee that the
      * hardware is actually finished.
      *
+     * <p><b>Use with caution on macOS.</b> Currently this may lead to deadlock on macOS because we
+     * block the GL thread when binding a Cocoa view to the GL context.</p>
+     *
      * <p>This is typically used right after destroying the <code>SwapChain</code>,
      * in cases where a guarantee about the SwapChain destruction is needed in a timely fashion,
      * such as when responding to Android's

android/filament-android/src/main/java/com/google/android/filament/Fence.java

@@ -37,6 +37,12 @@ public class Fence {
         TIMEOUT_EXPIRED
     }
 
+    /**
+     * Blocks the current thread until the Fence signals.
+     *
+     * <p><b>Use with caution on macOS.</b> Currently this may lead to deadlock on macOS because we
+     * block the GL thread when binding a Cocoa view to the GL context.</p>
+     */
     public FenceStatus wait(@NonNull Mode mode, long timeoutNanoSeconds) {
         int nativeResult = nWait(getNativeObject(), mode.ordinal(), timeoutNanoSeconds);
         switch (nativeResult) {

filament/include/filament/Engine.h

@@ -358,6 +358,9 @@ public:
      * all commands to this point are executed. Note that this doesn't guarantee that the
      * hardware is actually finished.
      *
+     * \warning Use with caution on macOS. Currently this may lead to deadlock on macOS because we
+     * block the GL thread when binding a Cocoa view to the GL context.
+     *
      * <p>This is typically used right after destroying the <code>SwapChain</code>,
      * in cases where a guarantee about the <code>SwapChain</code> destruction is needed in a
      * timely fashion, such as when responding to Android's

filament/include/filament/Fence.h

@@ -58,6 +58,9 @@ public:
      *
      * Blocks the current thread until the Fence signals.
      *
+     * \warning Use with caution on macOS. Currently this may lead to deadlock on macOS because we
+     * block the GL thread when binding a Cocoa view to the GL context.
+     *
      * @param mode      Whether the command stream is flushed before waiting or not.
      * @param timeout   Wait time out. Using a \p timeout of 0 is a way to query the state of the fence.
      *                  A \p timeout value of FENCE_WAIT_FOR_EVER is used to disable the timeout.