[libcamera-devel] [PATCH 03/30] libcamera: buffer: Add BufferInfo container for buffer metadata information

[Niklas Söderlund]

For FrameBuffers the metadata information gathered when a buffer is
captured will not be stored directly in the buffer object but in its
own container. Add the BufferInfo class to hold this information.

Signed-off-by: Niklas Söderlund <niklas.soderlund at ragnatech.se>
---
 include/libcamera/buffer.h | 30 +++++++++++++
 src/libcamera/buffer.cpp   | 92 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 122 insertions(+)

diff --git a/include/libcamera/buffer.h b/include/libcamera/buffer.h
index 80602124f24be4a0..7302b9f32ce8c50d 100644
--- a/include/libcamera/buffer.h
+++ b/include/libcamera/buffer.h
@@ -16,6 +16,36 @@ namespace libcamera {
 class Request;
 class Stream;
 
+class BufferInfo
+{
+public:
+	enum Status {
+		BufferSuccess,
+		BufferError,
+		BufferCancelled,
+	};
+
+	struct Plane {
+		unsigned int bytesused;
+	};
+
+	BufferInfo();
+
+	void update(Status status, unsigned int sequence, uint64_t timestamp,
+		    const std::vector<Plane> &planes);
+
+	Status status() const { return status_; }
+	unsigned int sequence() const { return sequence_; }
+	uint64_t timestamp() const { return timestamp_; }
+	const std::vector<Plane> &planes() const { return planes_; }
+
+private:
+	Status status_;
+	unsigned int sequence_;
+	uint64_t timestamp_;
+	std::vector<Plane> planes_;
+};
+
 class Plane final
 {
 public:
diff --git a/src/libcamera/buffer.cpp b/src/libcamera/buffer.cpp
index 960eeb8f7d193ddd..4acff216cafba484 100644
--- a/src/libcamera/buffer.cpp
+++ b/src/libcamera/buffer.cpp
@@ -23,6 +23,98 @@ namespace libcamera {
 
 LOG_DEFINE_CATEGORY(Buffer)
 
+/**
+ * \class BufferInfo
+ * \brief Dynamic buffer metadata
+ *
+ * The BufferInfo class references a buffers dynamic metadata related to the
+ * frame contained in the buffer.
+ */
+
+/**
+ * \enum BufferInfo::Status
+ * Buffer completion status
+ * \var BufferInfo::BufferSuccess
+ * The buffer has completed with success and contains valid data. All its other
+ * metadata (such as bytesused(), timestamp() or sequence() number) are valid.
+ * \var BufferInfo::BufferError
+ * The buffer has completed with an error and doesn't contain valid data. Its
+ * other metadata are valid.
+ * \var BufferInfo::BufferCancelled
+ * The buffer has been cancelled due to capture stop. Its other metadata are
+ * invalid and shall not be used.
+ */
+
+/**
+ * \struct BufferInfo::Plane
+ * \brief Plane specific buffer information
+ */
+
+/**
+ * \var BufferInfo::Plane::bytesused
+ * \brief Retrieve the number of bytes occupied by the data in the plane
+ * \return Number of bytes occupied in the plane
+ */
+
+BufferInfo::BufferInfo()
+	: status_(BufferError), sequence_(0), timestamp_(0)
+{
+}
+
+/**
+ * \brief Uptade the buffer information
+ * \param[in] status New buffer status
+ * \param[in] sequence New buffer sequence
+ * \param[in] timestamp New buffer timestamp
+ * \param[in] planes New buffer plane meta data
+ *
+ * Update the stored buffer meta data information.
+ */
+void BufferInfo::update(Status status, unsigned int sequence,
+			uint64_t timestamp, const std::vector<Plane> &planes)
+{
+	status_ = status;
+	sequence_ = sequence;
+	timestamp_ = timestamp;
+	planes_ = planes;
+}
+
+/**
+ * \fn BufferInfo::status()
+ * \brief Retrieve the buffer status
+ *
+ * The buffer status reports whether the buffer has completed successfully
+ * (BufferSuccess) or if an error occurred (BufferError).
+ *
+ * \return The buffer status
+ */
+
+/**
+ * \fn BufferInfo::sequence()
+ * \brief Retrieve the buffer sequence number
+ *
+ * The sequence number is a monotonically increasing number assigned to the
+ * buffer processed by the stream. Gaps in the sequence numbers indicate
+ * dropped frames.
+ *
+ * \return Sequence number of the buffer
+ */
+
+/**
+ * \fn BufferInfo::timestamp()
+ * \brief Retrieve the time when the buffer was processed
+ *
+ * The timestamp is expressed as a number of nanoseconds since the epoch.
+ *
+ * \return Timestamp when the buffer was processed
+ */
+
+/**
+ * \fn BufferInfo::planes()
+ * \brief Retrieve the plane(s) information for the buffer
+ * \return A array holding all plane information for the buffer
+ */
+
 /**
  * \class Plane
  * \brief A memory region to store a single plane of a frame
-- 
2.24.0