[libcamera-devel] [PATCH 2/2] android: camera_request: Lifetime of a Camera3RequestDescriptor

[Umang Jain]

This commit provides a sketch regarding Camera3RequestDescriptor
which aids tracking each capture reuqest placed by the android
framework to libcamera HAL.

Signed-off-by: Umang Jain <umang.jain at ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
---
 src/android/camera_request.cpp | 88 ++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)

diff --git a/src/android/camera_request.cpp b/src/android/camera_request.cpp
index 027b46d3..fceaa1f7 100644
--- a/src/android/camera_request.cpp
+++ b/src/android/camera_request.cpp
@@ -18,6 +18,94 @@ using namespace libcamera;
  *
  * A utility class that groups information about a capture request to be later
  * reused at request complete time to notify the framework.
+ *
+ *******************************************************************************
+ * Lifetime of a Camera3RequestDescriptor tracking a capture request placed by
+ * Android Framework
+ *******************************************************************************
+ *
+ *
+ *  Android Framework
+ *     │
+ *     │    ┌──────────────────────────────────┐
+ *     │    │camera3_capture_request_t         │
+ *     │    │                                  │
+ *     │    │Requested output streams          │
+ *     │    │  stream1   stream2   stream3 ... │
+ *     │    └──────────────────────────────────┘
+ *     ▼
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │ libcamera HAL                                               │
+ * ├─────────────────────────────────────────────────────────────┤
+ * │  CameraDevice                                               │
+ * │                                                             │
+ * │  processCaptureRequest(camera3_capture_request_t request)   │
+ * │                                                             │
+ * │   - Create Camera3RequestDescriptor tracking this request   │
+ * │   - Streams requiring post-processing are stored in the     │
+ * │     pendingStreamsToProcess map                             │
+ * │   - Add this Camera3RequestDescriptor to descriptors' queue │
+ * │     CameraDevice::descriptors_                              │
+ * │                                                             │ ┌─────────────────────────┐
+ * │   - Queue the capture request to libcamera core ────────────┤►│libcamera core           │
+ * │                                                             │ ├─────────────────────────┤
+ * │                                                             │ │- Capture from Camera    │
+ * │                                                             │ │                         │
+ * │                                                             │ │- Emit                   │
+ * │                                                             │ │  Camera::requestComplete│
+ * │  requestCompleted(Request *request) ◄───────────────────────┼─┼────                     │
+ * │                                                             │ │                         │
+ * │   - Check request completion status                         │ └─────────────────────────┘
+ * │                                                             │
+ * │   - if (pendingStreamsToProcess > 0)                        │
+ * │      Queue all entries from pendingStreamsToProcess         │
+ * │    else                                   │                 │
+ * │      completeDescriptor()                 │                 └──────────────────────┐
+ * │                                           │                                        │
+ * │                ┌──────────────────────────┴───┬──────────────────┐                 │
+ * │                │                              │                  │                 │
+ * │     ┌──────────▼────────────┐     ┌───────────▼─────────┐        ▼                 │
+ * │     │CameraStream1          │     │CameraStream2        │      ....                │
+ * │     ├┬───┬───┬──────────────┤     ├┬───┬───┬────────────┤                          │
+ * │     ││   │   │              │     ││   │   │            │                          │
+ * │     │▼───▼───▼──────────────┤     │▼───▼───▼────────────┤                          │
+ * │     │PostProcessorWorker    │     │PostProcessorWorker  │                          │
+ * │     │                       │     │                     │                          │
+ * │     │ +------------------+  │     │ +------------------+│                          │
+ * │     │ | PostProcessor    |  │     │ | PostProcessor    |│                          │
+ * │     │ |     process()    |  │     │ |     process()    |│                          │
+ * │     │ |                  |  │     │ |                  |│                          │
+ * │     │ | Emit             |  │     │ | Emit             |│                          │
+ * │     │ | processComplete  |  │     │ | processComplete  |│                          │
+ * │     │ |                  |  │     │ |                  |│                          │
+ * │     │ +--------------│---+  │     │ +--------------│---+│                          │
+ * │     │                │      │     │                │    │                          │
+ * │     │                │      │     │                │    │                          │
+ * │     └────────────────┼──────┘     └────────────────┼────┘                          │
+ * │                      │                             │                               │
+ * │                      │                             │                               │
+ * │                      │                             │                               │
+ * │                      ▼                             ▼                               │
+ * │ +---------------------------------------+     +--------------+                     │
+ * │ | CameraDevice                          |     |              |                     │
+ * │ |                                       |     |              |                     │
+ * │ | streamProcessingComplete()            |     |              |                     │
+ * │ |                                       |     |              |                     │
+ * │ | - Check and set buffer status         |     |     ....     |                     │
+ * │ | - Remove post+processing entry        |     |              |                     │
+ * │ |   from pendingStreamsToProcess        |     |              |                     │
+ * │ |                                       |     |              |                     │
+ * │ | - if (pendingStreamsToProcess.empty())|     |              |                     │
+ * │ |        completeDescriptor             |     |              |                     │
+ * │ |                                       |     |              |                     │
+ * │ +---------------------------------------+     +--------------+                     │
+ * │                                                                                    │
+ * └────────────────────────────────────────────────────────────────────────────────────┘
+ *
+ *   +-------------+
+ *   |             | - PostProcessorWorker's thread
+ *   |             |
+ *   +-------------+
  */
 
 Camera3RequestDescriptor::Camera3RequestDescriptor(
-- 
2.31.1