[common/client] ivshmem: add portable external frames

client/include/interface/external_frame.h

@@ -0,0 +1,88 @@
+/**
+ * Looking Glass
+ * Copyright © 2017-2026 The Looking Glass Authors
+ * https://looking-glass.io
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc., 59
+ * Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+
+#ifndef _H_LG_CLIENT_EXTERNAL_FRAME_
+#define _H_LG_CLIENT_EXTERNAL_FRAME_
+
+#include <stdbool.h>
+#include <stddef.h>
+
+typedef enum LG_ExternalFrameType
+{
+  LG_EXTERNAL_FRAME_INVALID = 0,
+  LG_EXTERNAL_FRAME_DMABUF  = 1,
+}
+LG_ExternalFrameType;
+
+typedef struct LG_ExternalFrame LG_ExternalFrame;
+
+/*
+ * A NULL pointer means there is no external resource. External frames own
+ * their native resource. Their address is a stable cache identity: a new
+ * native export must use a new object. Query results are immutable, borrowed,
+ * and remain valid while any reference to the object is held. Consumers must
+ * never close or otherwise release a queried resource.
+ *
+ * LG_EXTERNAL_FRAME_DMABUF queries return one native file descriptor in an
+ * int-sized result buffer.
+ */
+typedef struct LG_ExternalFrameOps
+{
+  LG_ExternalFrameType type;
+  void (*retain )(LG_ExternalFrame * frame);
+  void (*release)(LG_ExternalFrame * frame);
+  bool (*query  )(const LG_ExternalFrame * frame, void * result,
+      size_t resultSize);
+}
+LG_ExternalFrameOps;
+
+struct LG_ExternalFrame
+{
+  const LG_ExternalFrameOps * ops;
+};
+
+static inline LG_ExternalFrameType lgExternalFrameType(
+    const LG_ExternalFrame * frame)
+{
+  return frame && frame->ops ? frame->ops->type : LG_EXTERNAL_FRAME_INVALID;
+}
+
+static inline LG_ExternalFrame * lgExternalFrameRetain(
+    LG_ExternalFrame * frame)
+{
+  if (frame)
+    frame->ops->retain(frame);
+  return frame;
+}
+
+static inline void lgExternalFrameRelease(LG_ExternalFrame * frame)
+{
+  if (frame)
+    frame->ops->release(frame);
+}
+
+static inline bool lgExternalFrameQuery(const LG_ExternalFrame * frame,
+    LG_ExternalFrameType type, void * result, size_t resultSize)
+{
+  return frame && frame->ops && frame->ops->type == type &&
+    frame->ops->query(frame, result, resultSize);
+}
+
+#endif

client/include/interface/renderer.h

@@ -26,6 +26,7 @@
 #include "app.h"
 #include "common/types.h"
 #include "common/framebuffer.h"
+#include "interface/external_frame.h"
 
 #define IS_LG_RENDERER_VALID(x) \
   ((x)->getName             && \
@@ -304,11 +305,13 @@ typedef struct LG_RendererOps
 
   /* called when there is a new frame. frameToken must remain attached to the
    * update if the renderer coalesces it, and must be reported by render only
-   * when that update is consumed. A non-NULL releaseFn transfers ownership to
-   * the renderer on success and must be called exactly once when the imported
-   * frame can no longer be sampled. Context: frameThread */
+   * when that update is consumed. On success, ownership of externalFrame and
+   * a non-NULL releaseFn transfers to the renderer. The external frame must be
+   * released and releaseFn called exactly once when the imported frame can no
+   * longer be sampled. Context: frameThread */
   bool (*onFrame)(LG_Renderer * renderer, const KVMFRFrameBuffer * frame,
-      int dmaFD, const KVMFRFrameDamageRect * damage, int damageCount,
+      LG_ExternalFrame * externalFrame, const KVMFRFrameDamageRect * damage,
+      int damageCount,
       LG_RendererFrameToken frameToken,
       LG_FrameReleaseFn releaseFn,
       void * releaseOpaque, uint64_t releaseHandle);

client/include/interface/transport.h

@@ -30,6 +30,7 @@
 #include "common/types.h"
 #include "interface/audio.h"
 #include "interface/clipboard.h"
+#include "interface/external_frame.h"
 #include "interface/input.h"
 
 #define LG_TRANSPORT_MAX_DAMAGE_RECTS LG_MAX_FRAME_DAMAGE_RECTS
@@ -343,7 +344,7 @@ typedef struct LG_TransportFrame
   const LG_TransportFrameFormat * format;
 
   const KVMFRFrameBuffer     * framebuffer;
-  int                          dmaFD;
+  LG_ExternalFrame           * externalFrame;
   const KVMFRFrameDamageRect * damageRects;
   uint32_t                     damageRectsCount;