[libcamera-devel] [RFC PATCH 1/2] android: Document the structures and functions for post-processing

[Umang Jain]

Specifically document:
 - CameraDevice::sendCaptureResults()
 - CameraDevice::completeDescriptor()
 - CameraDevice::streamProcessingComplete()

 - CameraStream::PostProcessorWorker class
 - Camera3RequestDescriptor::StreamBuffer structure

Signed-off-by: Umang Jain <umang.jain at ideasonboard.com>
---
 src/android/camera_device.cpp  | 35 +++++++++++++++++++++++++++++++
 src/android/camera_request.cpp | 38 ++++++++++++++++++++++++++++++++++
 src/android/camera_stream.cpp  | 12 +++++++++++
 3 files changed, 85 insertions(+)

diff --git a/src/android/camera_device.cpp b/src/android/camera_device.cpp
index f2e0bdbd..fb46be4d 100644
--- a/src/android/camera_device.cpp
+++ b/src/android/camera_device.cpp
@@ -1147,6 +1147,16 @@ void CameraDevice::requestComplete(Request *request)
 	}
 }
 
+/**
+ * \brief Complete the Camera3RequestDescriptor
+ * \param[in] descriptor The Camera3RequestDescriptor deemed to be complete
+ *
+ * Marks the Camera3RequestDescriptor as 'complete'. This means all the streams
+ * in the Camera3RequestDescriptor have completed capture (or generated via
+ * post-processing) and is ready be sent back to the framework.
+ *
+ * \context This function is \threadsafe.
+ */
 void CameraDevice::completeDescriptor(Camera3RequestDescriptor *descriptor)
 {
 	MutexLocker lock(descriptorsMutex_);
@@ -1155,6 +1165,17 @@ void CameraDevice::completeDescriptor(Camera3RequestDescriptor *descriptor)
 	sendCaptureResults();
 }
 
+/**
+ * \brief Sequentially send capture results to the framework
+ *
+ * Inspect the head of the descriptors' queue and see if it is ready to be sent
+ * back to the framework. Populate a locally-scoped camera3_capture_result_t
+ * using the fields of the descriptor and send the capture result back by
+ * calling the process_capture_result() callback.
+ *
+ * This function should never be called directly in the codebase. Use
+ * completeDescriptor() instead.
+ */
 void CameraDevice::sendCaptureResults()
 {
 	while (!descriptors_.empty() && !descriptors_.front()->isPending()) {
@@ -1214,6 +1235,20 @@ void CameraDevice::setBufferStatus(Camera3RequestDescriptor::StreamBuffer &strea
 	}
 }
 
+/**
+ * \brief Handle post-processing completion of a stream in a capture request
+ * \param[in] streamBuffer The StreamBuffer for which processing is complete
+ * \param[in] status Stream post-processing status
+ *
+ * This is invoked in the post-processor's thread whenever a camera stream has
+ * finished post processing. The corresponding entry is dropped from the
+ * descriptor's pendingStreamsToProcess_ map.
+ *
+ * If the pendingStreamsToProcess_ map is found to be empty, it is perceived
+ * that all the streams requiring to be generated from post-processing have been
+ * completed. Mark the descriptor as complete using completeDescriptor() in that
+ * case.
+ */
 void CameraDevice::streamProcessingComplete(Camera3RequestDescriptor::StreamBuffer *streamBuffer,
 					    Camera3RequestDescriptor::Status status)
 {
diff --git a/src/android/camera_request.cpp b/src/android/camera_request.cpp
index 8162aa78..4e017792 100644
--- a/src/android/camera_request.cpp
+++ b/src/android/camera_request.cpp
@@ -53,6 +53,44 @@ Camera3RequestDescriptor::Camera3RequestDescriptor(
 
 Camera3RequestDescriptor::~Camera3RequestDescriptor() = default;
 
+/**
+ * \struct Camera3RequestDescriptor::StreamBuffer
+ * \brief Groups information for per-stream buffer of Camera3RequestDescriptor
+ *
+ * A capture request placed to the libcamera HAL can contain multiple streams.
+ * Each stream will have an associated buffer to be filled. StreamBuffer struct
+ * tracks this buffer with contextual information which aids in the stream's
+ * generation. The generation of stream will depend on its type (refer
+ * CameraStream::Type documentation).
+ *
+ * \var Camera3RequestDescriptor::StreamBuffer::stream
+ * \brief Corresponding pointer to CameraStream
+ *
+ * \var Camera3RequestDescriptor::StreamBuffer::camera3Buffer
+ * \brief Native handle to the buffer
+ *
+ * \var Camera3RequestDescriptor::StreamBuffer::frameBuffer
+ * \brief Encapsulate the dmabuf handle inside a libcamera::FrameBuffer for
+ * direct streams
+ *
+ * \var Camera3RequestDescriptor::StreamBuffer::fence
+ * \brief Acquire fence of the buffer
+ *
+ * \var Camera3RequestDescriptor::StreamBuffer::status
+ * \brief Track the status of the buffer
+ *
+ * \var Camera3RequestDescriptor::StreamBuffer::internalBuffer
+ * \brief Pointer to a buffer internally handled by CameraStream (if any)
+ *
+ * \var Camera3RequestDescriptor::StreamBuffer::srcBuffer
+ * \brief Pointer to source frame buffer required for post-processing
+ *
+ * \var Camera3RequestDescriptor::StreamBuffer::dstBuffer
+ * \brief Pointer to destination frame buffer required for post-processing
+ *
+ * \var Camera3RequestDescriptor::StreamBuffer::request
+ * \brief Back pointer to Camera3RequestDescriptor to which StreamBuffer belongs
+ */
 Camera3RequestDescriptor::StreamBuffer::StreamBuffer(
 	CameraStream *cameraStream, const camera3_stream_buffer_t &buffer,
 	Camera3RequestDescriptor *requestDescriptor)
diff --git a/src/android/camera_stream.cpp b/src/android/camera_stream.cpp
index 9023c13c..3cda58c9 100644
--- a/src/android/camera_stream.cpp
+++ b/src/android/camera_stream.cpp
@@ -231,6 +231,18 @@ void CameraStream::putBuffer(FrameBuffer *buffer)
 	buffers_.push_back(buffer);
 }
 
+/**
+ * \class CameraStream::PostProcessorWorker
+ * \brief Post process a CameraStream on an internal thread
+ *
+ * If the association between CameraStream and camera3_stream_t dictated by
+ * CameraStream::Type is internal or mapped, the stream is generated by post
+ * processing of a libcamera stream. Such a request is queued to
+ * PostProcessorWorker in CameraStream::process(). A queue of post-processing
+ * requests is maintained by the PostProcessorWorker and it will run the
+ * post-processing on an internal thread as soon as any request is available on
+ * its queue.
+ */
 CameraStream::PostProcessorWorker::PostProcessorWorker(PostProcessor *postProcessor)
 	: postProcessor_(postProcessor)
 {
-- 
2.31.0