[libcamera-devel] [PATCH v3 2/8] cam: Add FrameSink base class

[Laurent Pinchart]

The FrameSink class serves as a base to implement components that
consume frames. This allows handling frame sinks in a generic way,
independent of their nature. The BufferWrite class will be ported to
FrameSink in a second step.

Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund at ragnatech.se>
Reviewed-by: Paul Elder <paul.elder at ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
Reviewed-by: Umang Jain <umang.jain at ideasonboard.com>
---
Changes since v2:

- Document the FrameSink class
- Update copyright year
- Rename consumeRequest() to processRequest() and requestReleased to
  requestProcessed
---
 src/cam/frame_sink.cpp | 67 ++++++++++++++++++++++++++++++++++++++++++
 src/cam/frame_sink.h   | 34 +++++++++++++++++++++
 src/cam/meson.build    |  1 +
 3 files changed, 102 insertions(+)
 create mode 100644 src/cam/frame_sink.cpp
 create mode 100644 src/cam/frame_sink.h

diff --git a/src/cam/frame_sink.cpp b/src/cam/frame_sink.cpp
new file mode 100644
index 000000000000..af21d575172e
--- /dev/null
+++ b/src/cam/frame_sink.cpp
@@ -0,0 +1,67 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+/*
+ * Copyright (C) 2021, Ideas on Board Oy
+ *
+ * frame_sink.cpp - Base Frame Sink Class
+ */
+
+#include "frame_sink.h"
+
+/**
+ * \class FrameSink
+ * \brief Abstract class to model a consumer of frames
+ *
+ * The FrameSink class models the consumer that processes frames after a request
+ * completes. It receives requests through processRequest(), and processes them
+ * synchronously or asynchronously. This allows frame sinks to hold onto frames
+ * for an extended period of time, for instance to display them until a new
+ * frame arrives.
+ *
+ * A frame sink processes whole requests, and is solely responsible for deciding
+ * how to handle different frame buffers in case multiple streams are captured.
+ */
+
+FrameSink::~FrameSink()
+{
+}
+
+int FrameSink::configure([[maybe_unused]] const libcamera::CameraConfiguration &config)
+{
+	return 0;
+}
+
+void FrameSink::mapBuffer([[maybe_unused]] libcamera::FrameBuffer *buffer)
+{
+}
+
+int FrameSink::start()
+{
+	return 0;
+}
+
+int FrameSink::stop()
+{
+	return 0;
+}
+
+/**
+ * \fn FrameSink::processRequest()
+ * \param[in] request The request
+ *
+ * This function is called to instruct the sink to process a request. The sink
+ * may process the request synchronously or queue it for asynchronous
+ * processing.
+ *
+ * When the request is processed synchronously, this function shall return true.
+ * The \a request shall not be accessed by the FrameSink after the function
+ * returns.
+ *
+ * When the request is processed asynchronously, the FrameSink temporarily takes
+ * ownership of the \a request. The function shall return false, and the
+ * FrameSink shall emit the requestProcessed signal when the request processing
+ * completes. If the stop() function is called before the request processing
+ * completes, it shall release the request synchronously.
+ *
+ * \return True if the request has been processed synchronously, false if
+ * processing has been queued
+ */
diff --git a/src/cam/frame_sink.h b/src/cam/frame_sink.h
new file mode 100644
index 000000000000..76e1fc30a905
--- /dev/null
+++ b/src/cam/frame_sink.h
@@ -0,0 +1,34 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+/*
+ * Copyright (C) 2021, Ideas on Board Oy
+ *
+ * frame_sink.h - Base Frame Sink Class
+ */
+#ifndef __CAM_FRAME_SINK_H__
+#define __CAM_FRAME_SINK_H__
+
+#include <libcamera/base/signal.h>
+
+namespace libcamera {
+class CameraConfiguration;
+class FrameBuffer;
+class Request;
+} /* namespace libcamera */
+
+class FrameSink
+{
+public:
+	virtual ~FrameSink();
+
+	virtual int configure(const libcamera::CameraConfiguration &config);
+
+	virtual void mapBuffer(libcamera::FrameBuffer *buffer);
+
+	virtual int start();
+	virtual int stop();
+
+	virtual bool processRequest(libcamera::Request *request) = 0;
+	libcamera::Signal<libcamera::Request *> requestProcessed;
+};
+
+#endif /* __CAM_FRAME_SINK_H__ */
diff --git a/src/cam/meson.build b/src/cam/meson.build
index 1e90ee521f74..649cc990d867 100644
--- a/src/cam/meson.build
+++ b/src/cam/meson.build
@@ -13,6 +13,7 @@ cam_sources = files([
     'buffer_writer.cpp',
     'camera_session.cpp',
     'event_loop.cpp',
+    'frame_sink.cpp',
     'main.cpp',
     'options.cpp',
     'stream_options.cpp',
-- 
Regards,

Laurent Pinchart