libcamera: buffer: Split memory information to BufferMemory

The Buffer class is a large beast the stores information about the
buffer memory, dynamic metadata related to the frame stored in the
buffer, and buffer reference data (in the index). In order to implement
buffer import we will need to extend this with dmabuf file descriptors,
making usage of the class even more complex.

Refactor the Buffer class by splitting the buffer memory information to
a BufferMemory class, and repurposing the Buffer class to reference a
buffer and to store dynamic metadata. The BufferMemory class becomes a
long term storage, valid and stable from the time buffer memory is
allocated to the time it is freed. The Buffer class, on the other hand,
becomes transient, is created on demand when an application requires a
buffer, is given to a request, and is deleted when the request
completes.

Buffer and BufferMemory don't need to be copied, so their copy
constructor and assignment operators are deleted.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>

1 files changed, 102 insertions, 62 deletions

diff --git a/src/libcamera/buffer.cpp b/src/libcamera/buffer.cpp
index c0a02094..ecbf2524 100644
--- a/src/libcamera/buffer.cpp
+++ b/src/libcamera/buffer.cpp
@@ -173,12 +173,78 @@ void *Plane::mem()
  */
 
 /**
- * \class Buffer
+ * \class BufferMemory
  * \brief A memory buffer to store an image
  *
- * The Buffer class represents the memory buffers used to store a
- * full frame image, which may contain multiple separate memory Plane
- * objects if the image format is multi-planar.
+ * The BufferMemory class represents the memory buffers used to store full frame
+ * images, which may contain multiple separate memory Plane objects if the
+ * image format is multi-planar.
+ */
+
+/**
+ * \fn BufferMemory::planes()
+ * \brief Retrieve the planes within the buffer
+ * \return A reference to a vector holding all Planes within the buffer
+ */
+
+/**
+ * \class BufferPool
+ * \brief A pool of buffers
+ *
+ * The BufferPool class groups together a collection of Buffers to store frames.
+ * The buffers must be exported by a device before they can be imported into
+ * another device for further use.
+ */
+
+BufferPool::~BufferPool()
+{
+	destroyBuffers();
+}
+
+/**
+ * \brief Create buffers in the Pool
+ * \param[in] count The number of buffers to create
+ */
+void BufferPool::createBuffers(unsigned int count)
+{
+	buffers_.resize(count);
+}
+
+/**
+ * \brief Release all buffers from pool
+ *
+ * If no buffers have been created or if buffers have already been released no
+ * operation is performed.
+ */
+void BufferPool::destroyBuffers()
+{
+	buffers_.resize(0);
+}
+
+/**
+ * \fn BufferPool::count()
+ * \brief Retrieve the number of buffers contained within the pool
+ * \return The number of buffers contained in the pool
+ */
+
+/**
+ * \fn BufferPool::buffers()
+ * \brief Retrieve all the buffers in the pool
+ * \return A vector containing all the buffers in the pool.
+ */
+
+/**
+ * \class Buffer
+ * \brief A buffer handle and dynamic metadata
+ *
+ * The Buffer class references a buffer memory and associates dynamic metadata
+ * related to the frame contained in the buffer. It allows referencing buffer
+ * memory through a single interface regardless of whether the memory is
+ * allocated internally in libcamera or provided externally through dmabuf.
+ *
+ * Buffer instances are allocated dynamically for a stream through
+ * Stream::createBuffer(), added to a request with Request::addBuffer() and
+ * deleted automatically after the request complete handler returns.
  */
 
 /**
@@ -195,9 +261,26 @@ void *Plane::mem()
  * invalid and shall not be used.
  */
 
-Buffer::Buffer()
-	: index_(-1), request_(nullptr)
+/**
+ * \brief Construct a buffer not associated with any stream
+ *
+ * This method constructs an orphaned buffer not associated with any stream. It
+ * is not meant to be called by applications, they should instead create buffers
+ * for a stream with Stream::createBuffer().
+ */
+Buffer::Buffer(unsigned int index, const Buffer *metadata)
+	: index_(index), status_(Buffer::BufferSuccess), request_(nullptr),
+	  stream_(nullptr)
 {
+	if (metadata) {
+		bytesused_ = metadata->bytesused_;
+		sequence_ = metadata->sequence_;
+		timestamp_ = metadata->timestamp_;
+	} else {
+		bytesused_ = 0;
+		sequence_ = 0;
+		timestamp_ = 0;
+	}
 }
 
 /**
@@ -207,12 +290,6 @@ Buffer::Buffer()
  */
 
 /**
- * \fn Buffer::planes()
- * \brief Retrieve the planes within the buffer
- * \return A reference to a vector holding all Planes within the buffer
- */
-
-/**
  * \fn Buffer::bytesused()
  * \brief Retrieve the number of bytes occupied by the data in the buffer
  * \return Number of bytes occupied in the buffer
@@ -265,6 +342,19 @@ Buffer::Buffer()
  */
 
 /**
+ * \fn Buffer::stream()
+ * \brief Retrieve the stream this buffer is associated with
+ *
+ * A Buffer is associated to the stream that created it with
+ * Stream::createBuffer() and the association is valid until the buffer is
+ * destroyed. Buffer instances that are created directly are not associated
+ * with any stream.
+ *
+ * \return The Stream the Buffer is associated with, or nullptr if the buffer
+ * is not associated with a stream
+ */
+
+/**
  * \brief Mark a buffer as cancel by setting its status to BufferCancelled
  */
 void Buffer::cancel()
@@ -282,54 +372,4 @@ void Buffer::cancel()
  * The intended callers are Request::prepare() and Request::completeBuffer().
  */
 
-/**
- * \class BufferPool
- * \brief A pool of buffers
- *
- * The BufferPool class groups together a collection of Buffers to store frames.
- * The buffers must be exported by a device before they can be imported into
- * another device for further use.
- */
-
-BufferPool::~BufferPool()
-{
-	destroyBuffers();
-}
-
-/**
- * \brief Create buffers in the Pool
- * \param[in] count The number of buffers to create
- */
-void BufferPool::createBuffers(unsigned int count)
-{
-	unsigned int index = 0;
-
-	buffers_.resize(count);
-	for (Buffer &buffer : buffers_)
-		buffer.index_ = index++;
-}
-
-/**
- * \brief Release all buffers from pool
- *
- * If no buffers have been created or if buffers have already been released no
- * operation is performed.
- */
-void BufferPool::destroyBuffers()
-{
-	buffers_.resize(0);
-}
-
-/**
- * \fn BufferPool::count()
- * \brief Retrieve the number of buffers contained within the pool
- * \return The number of buffers contained in the pool
- */
-
-/**
- * \fn BufferPool::buffers()
- * \brief Retrieve all the buffers in the pool
- * \return A vector containing all the buffers in the pool.
- */
-
 } /* namespace libcamera */