libcamera: buffer: Add buffer completion status

Add a new field to the Buffer class to report its completion status,
with a new cancel() method to mark the buffer as cancelled.

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

include/libcamera/buffer.h

@@ -40,12 +40,19 @@ private:
 class Buffer final
 {
 public:
+	enum Status {
+		BufferSuccess,
+		BufferError,
+		BufferCancelled,
+	};
+
 	Buffer();
 
 	unsigned int index() const { return index_; }
 	unsigned int bytesused() const { return bytesused_; }
 	uint64_t timestamp() const { return timestamp_; }
 	unsigned int sequence() const { return sequence_; }
+	Status status() const { return status_; }
 	std::vector<Plane> &planes() { return planes_; }
 
 	Signal<Buffer *> completed;
@@ -54,10 +61,13 @@ private:
 	friend class BufferPool;
 	friend class V4L2Device;
 
+	void cancel();
+
 	unsigned int index_;
 	unsigned int bytesused_;
 	uint64_t timestamp_;
 	unsigned int sequence_;
+	Status status_;
 
 	std::vector<Plane> planes_;
 };

src/libcamera/buffer.cpp

@@ -181,6 +181,20 @@ void *Plane::mem()
  * objects if the image format is multi-planar.
  */
 
+/**
+ * \enum Buffer::Status
+ * Buffer completion status
+ * \var Buffer::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 Buffer::BufferError
+ * The buffer has completed with an error and doesn't contain valid data. Its
+ * other metadata are valid.
+ * \var Buffer::BufferCancelled
+ * The buffer has been cancelled due to capture stop. Its other metadata are
+ * invalid and shall not be used.
+ */
+
 Buffer::Buffer()
 	: index_(-1)
 {
@@ -229,6 +243,27 @@ Buffer::Buffer()
  * \return Sequence number of the buffer
  */
 
+/**
+ * \fn Buffer::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
+ */
+
+/**
+ * \brief Mark a buffer as cancel by setting its status to BufferCancelled
+ */
+void Buffer::cancel()
+{
+	bytesused_ = 0;
+	timestamp_ = 0;
+	sequence_ = 0;
+	status_ = BufferCancelled;
+}
+
 /**
  * \class BufferPool
  * \brief A pool of buffers

src/libcamera/v4l2_device.cpp

@@ -799,6 +799,8 @@ Buffer *V4L2Device::dequeueBuffer()
 	buffer->timestamp_ = buf.timestamp.tv_sec * 1000000000ULL
 			   + buf.timestamp.tv_usec * 1000ULL;
 	buffer->sequence_ = buf.sequence;
+	buffer->status_ = buf.flags & V4L2_BUF_FLAG_ERROR
+			? Buffer::BufferError : Buffer::BufferSuccess;
 
 	return buffer;
 }