From b0337f29daadefcd61c3e811808047d24989d9b2 Mon Sep 17 00:00:00 2001
From: Jakob Bornecrantz <jakob@collabora.com>
Date: Wed, 10 Jul 2019 12:56:03 +0100
Subject: [PATCH] xrt: Add frameserver interface

---
 src/xrt/include/xrt/xrt_frameserver.h | 220 ++++++++++++++++++++++++++
 1 file changed, 220 insertions(+)
 create mode 100644 src/xrt/include/xrt/xrt_frameserver.h

diff --git a/src/xrt/include/xrt/xrt_frameserver.h b/src/xrt/include/xrt/xrt_frameserver.h
new file mode 100644
index 000000000..56d4afde2
--- /dev/null
+++ b/src/xrt/include/xrt/xrt_frameserver.h
@@ -0,0 +1,220 @@
+// Copyright 2019, Collabora, Ltd.
+// SPDX-License-Identifier: BSL-1.0
+/*!
+ * @file
+ * @brief  Frameserver interface for video drivers.
+ * @author Pete Black <pblack@collabora.com>
+ * @author Ryan Pavlik <ryan.pavlik@collabora.com>
+ * @author Jakob Bornecrantz <jakob@collabora.com>
+ * @ingroup xrt_iface
+ */
+
+#pragma once
+
+#include "xrt/xrt_defines.h"
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/*!
+ * What type of stereo format this frame has.
+ *
+ * @ingroup xrt_iface
+ */
+enum xrt_fs_stereo_format
+{
+	XRT_FS_STEREO_NONE,
+	XRT_FS_STEREO_SBS, //!< Side by side
+	XRT_FS_STEREO_OAU, //!< Over & Under
+};
+
+/*!
+ * Basic frame data structure - holds a pointer to buffer.
+ *
+ * @ingroup xrt_iface
+ */
+struct xrt_fs_frame
+{
+	uint32_t width;
+	uint32_t height;
+	size_t stride;
+	size_t size;
+	uint8_t *data;
+
+	enum xrt_format format;
+	enum xrt_fs_stereo_format stereo_format;
+
+	uint64_t timestamp;
+	uint64_t source_timestamp;
+	uint64_t source_sequence; //!< sequence id
+	uint64_t source_id; //!< Which @ref xrt_fs this frame originated from.
+};
+
+/*!
+ * A object that is sent frames.
+ *
+ * @ingroup xrt_iface
+ */
+struct xrt_fs_sink
+{
+	/*!
+	 * Push a frame into the sink.
+	 */
+	void (*push_frame)(struct xrt_fs_sink *sink,
+	                   struct xrt_fs_frame *frame);
+};
+
+/*!
+ * Controlling the camera capture parameters
+ *
+ * Used to configure cameras. since there is no guarantee every
+ * frameserver will support any/all of these params, a 'best effort'
+ * should be made to apply them. all numeric values are normalised
+ * floats for broad applicability.
+ *
+ * @ingroup xrt_iface
+ */
+struct xrt_fs_capture_parameters
+{
+	float gain;
+	float exposure;
+};
+
+struct xrt_fs_mode
+{
+	uint32_t width;
+	uint32_t height;
+	enum xrt_format format;
+	enum xrt_fs_stereo_format stereo_format;
+};
+
+/*!
+ * Frameserver that generates frame, multiple subframes (like stereo and
+ * mipmaps) can be generate in one frame.
+ *
+ * @ingroup xrt_iface
+ */
+struct xrt_fs
+{
+	/*!
+	 * All frames produced by this frameserver is tagged with this id.
+	 */
+	uint64_t source_id;
+
+	/*!
+	 * Enumerate all available modes that this frameserver supports.
+	 */
+	bool (*enumerate_modes)(struct xrt_fs *xfs,
+	                        struct xrt_fs_mode **out_modes,
+	                        uint32_t *out_count);
+
+	/*!
+	 * Set the capture parameters, may not be supported on all capture
+	 * devices.
+	 */
+	bool (*configure_capture)(struct xrt_fs *xfs,
+	                          struct xrt_fs_capture_parameters *cp);
+
+	/*!
+	 * Start the capture stream.
+	 */
+	bool (*stream_start)(struct xrt_fs *xfs, uint32_t descriptor_index);
+
+	/*!
+	 * Stop the capture stream.
+	 */
+	bool (*stream_stop)(struct xrt_fs *xfs);
+
+	/*!
+	 * Is the capture stream running.
+	 */
+	bool (*is_running)(struct xrt_fs *xfs);
+
+	/*!
+	 * Destroy the frameserver, also stops the capture stream.
+	 */
+	void (*destroy)(struct xrt_fs *xfs);
+};
+
+/*!
+ * Helper for xrt_fs::enumerate_modes.
+ *
+ * @ingroup xrt_iface
+ */
+static inline XRT_MAYBE_UNUSED bool
+xrt_fs_enumerate_modes(struct xrt_fs *xfs,
+                       struct xrt_fs_mode **out_modes,
+                       uint32_t *out_count)
+{
+	return xfs->enumerate_modes(xfs, out_modes, out_count);
+}
+
+/*!
+ * Helper for xrt_fs::configure_capture.
+ *
+ * @ingroup xrt_iface
+ */
+static inline XRT_MAYBE_UNUSED bool
+xrt_fs_configure_capture(struct xrt_fs *xfs,
+                         struct xrt_fs_capture_parameters *cp)
+{
+	return xfs->configure_capture(xfs, cp);
+}
+
+/*!
+ * Helper for xrt_fs::stream_start.
+ *
+ * @ingroup xrt_iface
+ */
+static inline XRT_MAYBE_UNUSED bool
+xrt_fs_stream_start(struct xrt_fs *xfs, uint32_t descriptor_index)
+{
+	return xfs->stream_start(xfs, descriptor_index);
+}
+
+/*!
+ * Helper for xrt_fs::stream_stop.
+ *
+ * @ingroup xrt_iface
+ */
+static inline XRT_MAYBE_UNUSED bool
+xrt_fs_stream_stop(struct xrt_fs *xfs)
+{
+	return xfs->stream_stop(xfs);
+}
+
+/*!
+ * Helper for xrt_fs::is_running.
+ *
+ * @ingroup xrt_iface
+ */
+static inline XRT_MAYBE_UNUSED bool
+xrt_fs_is_running(struct xrt_fs *xfs)
+{
+	return xfs->is_running(xfs);
+}
+
+/*!
+ * Helper for xrt_fs::destroy.
+ *
+ * @ingroup xrt_iface
+ */
+static inline XRT_MAYBE_UNUSED void
+xrt_fs_destroy(struct xrt_fs **xfs_ptr)
+{
+	struct xrt_fs *xfs = *xfs_ptr;
+	if (xfs == NULL) {
+		return;
+	}
+
+	xfs->destroy(xfs);
+	*xfs_ptr = NULL;
+}
+
+
+#ifdef __cplusplus
+}
+#endif