[{"id":22207,"web_url":"https://patchwork.libcamera.org/comment/22207/","msgid":"<164612685751.2188904.6594778238003602197@Monstersaurus>","date":"2022-03-01T09:27:37","subject":"Re: [libcamera-devel] [PATCH 1/2] android: Document the structures\n\tand functions for post-processing","submitter":{"id":4,"url":"https://patchwork.libcamera.org/api/people/4/","name":"Kieran Bingham","email":"kieran.bingham@ideasonboard.com"},"content":"Quoting Umang Jain (2022-01-04 06:52:00)\n> Specifically document:\n> - CameraDevice::sendCaptureResults()\n> - CameraDevice::completeDescriptor()\n> - CameraDevice::streamProcessingComplete()\n> \n> - CameraStream::PostProcessorWorker class\n> - Camera3RequestDescriptor::StreamBuffer structure\n> \n> Signed-off-by: Umang Jain \n> Reviewed-by: Laurent Pinchart \n> ---\n> src/android/camera_device.cpp | 37 +++++++++++++++++++++++++++++++++\n> src/android/camera_request.cpp | 38 ++++++++++++++++++++++++++++++++++\n> src/android/camera_stream.cpp | 12 +++++++++++\n> 3 files changed, 87 insertions(+)\n> \n> diff --git a/src/android/camera_device.cpp b/src/android/camera_device.cpp\n> index 83825736..00d48471 100644\n> --- a/src/android/camera_device.cpp\n> +++ b/src/android/camera_device.cpp\n> @@ -1164,6 +1164,17 @@ void CameraDevice::requestComplete(Request *request)\n> }\n> }\n> \n> +/**\n> + * \\brief Complete the Camera3RequestDescriptor\n> + * \\param[in] descriptor The Camera3RequestDescriptor that has completed\n> + *\n> + * The function marks the Camera3RequestDescriptor as 'complete'. It shall be\n> + * called when all the streams in the Camera3RequestDescriptor have completed\n> + * capture (or have been generated via post-processing) and the request is ready\n> + * to be sent back to the framework.\n> + *\n> + * \\context This function is \\threadsafe.\n> + */\n> void CameraDevice::completeDescriptor(Camera3RequestDescriptor *descriptor)\n> {\n> MutexLocker lock(descriptorsMutex_);\n> @@ -1172,6 +1183,19 @@ void CameraDevice::completeDescriptor(Camera3RequestDescriptor *descriptor)\n> sendCaptureResults();\n> }\n> \n> +/**\n> + * \\brief Sequentially send capture results to the framework\n> + *\n> + * Iterate over the descriptors queue to send completed descriptors back to the\n> + * framework, in the same order as they have been queued. For each complete\n> + * descriptor, populate a locally-scoped camera3_capture_result_t from the\n> + * descriptor, send the capture result back by calling the\n> + * process_capture_result() callback, and remove the descriptor from the queue.\n> + * Stop iterating if the descriptor at the front of the queue is not complete.\n> + *\n> + * This function should never be called directly in the codebase. Use\n> + * completeDescriptor() instead.\n> + */\n> void CameraDevice::sendCaptureResults()\n> {\n> while (!descriptors_.empty() && !descriptors_.front()->isPending()) {\n> @@ -1231,6 +1255,19 @@ void CameraDevice::setBufferStatus(Camera3RequestDescriptor::StreamBuffer &strea\n> }\n> }\n> \n> +/**\n> + * \\brief Handle post-processing completion of a stream in a capture request\n> + * \\param[in] streamBuffer The StreamBuffer for which processing is complete\n> + * \\param[in] status Stream post-processing status\n> + *\n> + * This function is called from the post-processor's thread whenever a camera\n> + * stream has finished post processing. The corresponding entry is dropped from\n> + * the descriptor's pendingStreamsToProcess_ map.\n> + *\n> + * If the pendingStreamsToProcess_ map is then empty, all streams requiring to\n> + * be generated from post-processing have been completed. Mark the descriptor as\n> + * complete using completeDescriptor() in that case.\n> + */\n> void CameraDevice::streamProcessingComplete(Camera3RequestDescriptor::StreamBuffer *streamBuffer,\n> Camera3RequestDescriptor::Status status)\n> {\n> diff --git a/src/android/camera_request.cpp b/src/android/camera_request.cpp\n> index 91776907..027b46d3 100644\n> --- a/src/android/camera_request.cpp\n> +++ b/src/android/camera_request.cpp\n> @@ -52,6 +52,44 @@ Camera3RequestDescriptor::Camera3RequestDescriptor(\n> \n> Camera3RequestDescriptor::~Camera3RequestDescriptor() = default;\n> \n> +/**\n> + * \\struct Camera3RequestDescriptor::StreamBuffer\n> + * \\brief Group information for per-stream buffer of Camera3RequestDescriptor\n> + *\n> + * A capture request placed to the libcamera HAL can contain multiple streams.\n> + * Each stream will have an associated buffer to be filled. StreamBuffer\n> + * tracks this buffer with contextual information which aids in the stream's\n> + * generation. The generation of the stream will depend on its type (refer to\n> + * the CameraStream::Type documentation).\n> + *\n> + * \\var Camera3RequestDescriptor::StreamBuffer::stream\n> + * \\brief Pointer to the corresponding CameraStream\n> + *\n> + * \\var Camera3RequestDescriptor::StreamBuffer::camera3Buffer\n> + * \\brief Native handle to the buffer\n> + *\n> + * \\var Camera3RequestDescriptor::StreamBuffer::frameBuffer\n> + * \\brief Encapsulate the dmabuf handle inside a libcamera::FrameBuffer for\n> + * direct streams\n> + *\n> + * \\var Camera3RequestDescriptor::StreamBuffer::fence\n> + * \\brief Acquire fence of the buffer\n> + *\n> + * \\var Camera3RequestDescriptor::StreamBuffer::status\n> + * \\brief Track the status of the buffer\n> + *\n> + * \\var Camera3RequestDescriptor::StreamBuffer::internalBuffer\n> + * \\brief Pointer to a buffer internally handled by CameraStream (if any)\n> + *\n> + * \\var Camera3RequestDescriptor::StreamBuffer::srcBuffer\n> + * \\brief Pointer to the source frame buffer used for post-processing\n> + *\n> + * \\var Camera3RequestDescriptor::StreamBuffer::dstBuffer\n> + * \\brief Pointer to the destination frame buffer used for post-processing\n> + *\n> + * \\var Camera3RequestDescriptor::StreamBuffer::request\n> + * \\brief Back pointer to Camera3RequestDescriptor to which StreamBuffer belongs\n\nI'd put some extra 'the' in here, but not essential:\n\n'to the Camera3RequestDescriptor'\n'which the StreamBuffer'\n\n\nReviewed-by: Kieran Bingham \n\n> + */\n> Camera3RequestDescriptor::StreamBuffer::StreamBuffer(\n> CameraStream *cameraStream, const camera3_stream_buffer_t &buffer,\n> Camera3RequestDescriptor *requestDescriptor)\n> diff --git a/src/android/camera_stream.cpp b/src/android/camera_stream.cpp\n> index c2157450..94f1884c 100644\n> --- a/src/android/camera_stream.cpp\n> +++ b/src/android/camera_stream.cpp\n> @@ -244,6 +244,18 @@ void CameraStream::putBuffer(FrameBuffer *buffer)\n> buffers_.push_back(buffer);\n> }\n> \n> +/**\n> + * \\class CameraStream::PostProcessorWorker\n> + * \\brief Post-process a CameraStream in an internal thread\n> + *\n> + * If the association between CameraStream and camera3_stream_t dictated by\n> + * CameraStream::Type is internal or mapped, the stream is generated by post\n> + * processing of a libcamera stream. Such a request is queued to a\n> + * PostProcessorWorker in CameraStream::process(). A queue of post-processing\n> + * requests is maintained by the PostProcessorWorker and it will run the\n> + * post-processing on an internal thread as soon as any request is available on\n> + * its queue.\n> + */\n> CameraStream::PostProcessorWorker::PostProcessorWorker(PostProcessor *postProcessor)\n> : postProcessor_(postProcessor)\n> {\n> -- \n> 2.31.1\n>","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id DD5F3BF415\n\tfor ;\n\tTue, 1 Mar 2022 09:27:41 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 2A53E61166;\n\tTue, 1 Mar 2022 10:27:41 +0100 (CET)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id C95786047A\n\tfor ;\n\tTue, 1 Mar 2022 10:27:39 +0100 (CET)","from pendragon.ideasonboard.com\n\t(cpc89244-aztw30-2-0-cust3082.18-1.cable.virginm.net [86.31.172.11])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 58D07478;\n\tTue, 1 Mar 2022 10:27:39 +0100 (CET)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"iCcK4cFd\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1646126859;\n\tbh=2TvTKLOD7ZtGR3DvGiliZV7T1xP7mzNmz5EQEUuSaG4=;\n\th=In-Reply-To:References:Subject:From:To:Date:From;\n\tb=iCcK4cFddKxGBzSf+w4bUiW8mG6nSzeulaKjTz2iFu15QGT3cXMV1BTnmqeRrL/sr\n\t3cq6enVpJ3OspZAQm70GIjpeXn92g1cLOzGZtrGl34KmMFijAr49aD5auYXZOO4fA/\n\tk67Z0DyfNETIAfR6GY7RBIllv4GJEtNLwW/ra/34=","Content-Type":"text/plain; charset=\"utf-8\"","MIME-Version":"1.0","Content-Transfer-Encoding":"quoted-printable","In-Reply-To":"<20220104065201.25744-2-umang.jain@ideasonboard.com>","References":"<20220104065201.25744-1-umang.jain@ideasonboard.com>\n\t<20220104065201.25744-2-umang.jain@ideasonboard.com>","From":"Kieran Bingham ","To":"Umang Jain ,\n\tlibcamera-devel@lists.libcamera.org","Date":"Tue, 01 Mar 2022 09:27:37 +0000","Message-ID":"<164612685751.2188904.6594778238003602197@Monstersaurus>","User-Agent":"alot/0.10","Subject":"Re: [libcamera-devel] [PATCH 1/2] android: Document the structures\n\tand functions for post-processing","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}},{"id":22209,"web_url":"https://patchwork.libcamera.org/comment/22209/","msgid":"<174c69ff-02f5-65d2-b230-f48ab9fec471@ideasonboard.com>","date":"2022-03-01T14:07:15","subject":"Re: [libcamera-devel] [PATCH 1/2] android: Document the structures\n\tand functions for post-processing","submitter":{"id":86,"url":"https://patchwork.libcamera.org/api/people/86/","name":"Umang Jain","email":"umang.jain@ideasonboard.com"},"content":"Hi Kieran,\n\nOn 3/1/22 14:57, Kieran Bingham wrote:\n> Quoting Umang Jain (2022-01-04 06:52:00)\n>> Specifically document:\n>> - CameraDevice::sendCaptureResults()\n>> - CameraDevice::completeDescriptor()\n>> - CameraDevice::streamProcessingComplete()\n>>\n>> - CameraStream::PostProcessorWorker class\n>> - Camera3RequestDescriptor::StreamBuffer structure\n>>\n>> Signed-off-by: Umang Jain \n>> Reviewed-by: Laurent Pinchart \n>> ---\n>> src/android/camera_device.cpp | 37 +++++++++++++++++++++++++++++++++\n>> src/android/camera_request.cpp | 38 ++++++++++++++++++++++++++++++++++\n>> src/android/camera_stream.cpp | 12 +++++++++++\n>> 3 files changed, 87 insertions(+)\n>>\n>> diff --git a/src/android/camera_device.cpp b/src/android/camera_device.cpp\n>> index 83825736..00d48471 100644\n>> --- a/src/android/camera_device.cpp\n>> +++ b/src/android/camera_device.cpp\n>> @@ -1164,6 +1164,17 @@ void CameraDevice::requestComplete(Request *request)\n>> }\n>> }\n>> \n>> +/**\n>> + * \\brief Complete the Camera3RequestDescriptor\n>> + * \\param[in] descriptor The Camera3RequestDescriptor that has completed\n>> + *\n>> + * The function marks the Camera3RequestDescriptor as 'complete'. It shall be\n>> + * called when all the streams in the Camera3RequestDescriptor have completed\n>> + * capture (or have been generated via post-processing) and the request is ready\n>> + * to be sent back to the framework.\n>> + *\n>> + * \\context This function is \\threadsafe.\n>> + */\n>> void CameraDevice::completeDescriptor(Camera3RequestDescriptor *descriptor)\n>> {\n>> MutexLocker lock(descriptorsMutex_);\n>> @@ -1172,6 +1183,19 @@ void CameraDevice::completeDescriptor(Camera3RequestDescriptor *descriptor)\n>> sendCaptureResults();\n>> }\n>> \n>> +/**\n>> + * \\brief Sequentially send capture results to the framework\n>> + *\n>> + * Iterate over the descriptors queue to send completed descriptors back to the\n>> + * framework, in the same order as they have been queued. For each complete\n>> + * descriptor, populate a locally-scoped camera3_capture_result_t from the\n>> + * descriptor, send the capture result back by calling the\n>> + * process_capture_result() callback, and remove the descriptor from the queue.\n>> + * Stop iterating if the descriptor at the front of the queue is not complete.\n>> + *\n>> + * This function should never be called directly in the codebase. Use\n>> + * completeDescriptor() instead.\n>> + */\n>> void CameraDevice::sendCaptureResults()\n>> {\n>> while (!descriptors_.empty() && !descriptors_.front()->isPending()) {\n>> @@ -1231,6 +1255,19 @@ void CameraDevice::setBufferStatus(Camera3RequestDescriptor::StreamBuffer &strea\n>> }\n>> }\n>> \n>> +/**\n>> + * \\brief Handle post-processing completion of a stream in a capture request\n>> + * \\param[in] streamBuffer The StreamBuffer for which processing is complete\n>> + * \\param[in] status Stream post-processing status\n>> + *\n>> + * This function is called from the post-processor's thread whenever a camera\n>> + * stream has finished post processing. The corresponding entry is dropped from\n>> + * the descriptor's pendingStreamsToProcess_ map.\n>> + *\n>> + * If the pendingStreamsToProcess_ map is then empty, all streams requiring to\n>> + * be generated from post-processing have been completed. Mark the descriptor as\n>> + * complete using completeDescriptor() in that case.\n>> + */\n>> void CameraDevice::streamProcessingComplete(Camera3RequestDescriptor::StreamBuffer *streamBuffer,\n>> Camera3RequestDescriptor::Status status)\n>> {\n>> diff --git a/src/android/camera_request.cpp b/src/android/camera_request.cpp\n>> index 91776907..027b46d3 100644\n>> --- a/src/android/camera_request.cpp\n>> +++ b/src/android/camera_request.cpp\n>> @@ -52,6 +52,44 @@ Camera3RequestDescriptor::Camera3RequestDescriptor(\n>> \n>> Camera3RequestDescriptor::~Camera3RequestDescriptor() = default;\n>> \n>> +/**\n>> + * \\struct Camera3RequestDescriptor::StreamBuffer\n>> + * \\brief Group information for per-stream buffer of Camera3RequestDescriptor\n>> + *\n>> + * A capture request placed to the libcamera HAL can contain multiple streams.\n>> + * Each stream will have an associated buffer to be filled. StreamBuffer\n>> + * tracks this buffer with contextual information which aids in the stream's\n>> + * generation. The generation of the stream will depend on its type (refer to\n>> + * the CameraStream::Type documentation).\n>> + *\n>> + * \\var Camera3RequestDescriptor::StreamBuffer::stream\n>> + * \\brief Pointer to the corresponding CameraStream\n>> + *\n>> + * \\var Camera3RequestDescriptor::StreamBuffer::camera3Buffer\n>> + * \\brief Native handle to the buffer\n>> + *\n>> + * \\var Camera3RequestDescriptor::StreamBuffer::frameBuffer\n>> + * \\brief Encapsulate the dmabuf handle inside a libcamera::FrameBuffer for\n>> + * direct streams\n>> + *\n>> + * \\var Camera3RequestDescriptor::StreamBuffer::fence\n>> + * \\brief Acquire fence of the buffer\n>> + *\n>> + * \\var Camera3RequestDescriptor::StreamBuffer::status\n>> + * \\brief Track the status of the buffer\n>> + *\n>> + * \\var Camera3RequestDescriptor::StreamBuffer::internalBuffer\n>> + * \\brief Pointer to a buffer internally handled by CameraStream (if any)\n>> + *\n>> + * \\var Camera3RequestDescriptor::StreamBuffer::srcBuffer\n>> + * \\brief Pointer to the source frame buffer used for post-processing\n>> + *\n>> + * \\var Camera3RequestDescriptor::StreamBuffer::dstBuffer\n>> + * \\brief Pointer to the destination frame buffer used for post-processing\n>> + *\n>> + * \\var Camera3RequestDescriptor::StreamBuffer::request\n>> + * \\brief Back pointer to Camera3RequestDescriptor to which StreamBuffer belongs\n> I'd put some extra 'the' in here, but not essential:\n>\n> 'to the Camera3RequestDescriptor'\n> 'which the StreamBuffer'\n\n\nOk, I'll fixup locally.\n\n>\n>\n> Reviewed-by: Kieran Bingham \n\n\nThanks!\n\n>\n>> + */\n>> Camera3RequestDescriptor::StreamBuffer::StreamBuffer(\n>> CameraStream *cameraStream, const camera3_stream_buffer_t &buffer,\n>> Camera3RequestDescriptor *requestDescriptor)\n>> diff --git a/src/android/camera_stream.cpp b/src/android/camera_stream.cpp\n>> index c2157450..94f1884c 100644\n>> --- a/src/android/camera_stream.cpp\n>> +++ b/src/android/camera_stream.cpp\n>> @@ -244,6 +244,18 @@ void CameraStream::putBuffer(FrameBuffer *buffer)\n>> buffers_.push_back(buffer);\n>> }\n>> \n>> +/**\n>> + * \\class CameraStream::PostProcessorWorker\n>> + * \\brief Post-process a CameraStream in an internal thread\n>> + *\n>> + * If the association between CameraStream and camera3_stream_t dictated by\n>> + * CameraStream::Type is internal or mapped, the stream is generated by post\n>> + * processing of a libcamera stream. Such a request is queued to a\n>> + * PostProcessorWorker in CameraStream::process(). A queue of post-processing\n>> + * requests is maintained by the PostProcessorWorker and it will run the\n>> + * post-processing on an internal thread as soon as any request is available on\n>> + * its queue.\n>> + */\n>> CameraStream::PostProcessorWorker::PostProcessorWorker(PostProcessor *postProcessor)\n>> : postProcessor_(postProcessor)\n>> {\n>> -- \n>> 2.31.1\n>>","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 4EC77BE08A\n\tfor ;\n\tTue, 1 Mar 2022 14:07:24 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 9A931604EE;\n\tTue, 1 Mar 2022 15:07:23 +0100 (CET)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id BDE95604EE\n\tfor ;\n\tTue, 1 Mar 2022 15:07:21 +0100 (CET)","from [192.168.1.106] (unknown [103.251.226.77])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 7F34AE41;\n\tTue, 1 Mar 2022 15:07:20 +0100 (CET)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"IDDa4fex\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1646143641;\n\tbh=XfXX2keUhz08p4yUeTQlekTeMtDRb/i0Mwx/EmfP4GM=;\n\th=Date:Subject:To:References:From:In-Reply-To:From;\n\tb=IDDa4fexK+djzJjBhhc1Dt0zPPchhEgM8++FXS8493xF2VeNJeBJowNX1SNXVQXKw\n\tfTBsp9jb12xUtl52fQ8qAsTFkoFXXlZo5D6hxulPAOSFS6FIm+Di2xP/NCNuF9YtVn\n\tGWV9PMGAfVvwOfBpUOMY7NjCVEKt1nLecEn2dN5o=","Message-ID":"<174c69ff-02f5-65d2-b230-f48ab9fec471@ideasonboard.com>","Date":"Tue, 1 Mar 2022 19:37:15 +0530","MIME-Version":"1.0","User-Agent":"Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101\n\tThunderbird/91.4.1","Content-Language":"en-US","To":"Kieran Bingham ,\n\tlibcamera-devel@lists.libcamera.org","References":"<20220104065201.25744-1-umang.jain@ideasonboard.com>\n\t<20220104065201.25744-2-umang.jain@ideasonboard.com>\n\t<164612685751.2188904.6594778238003602197@Monstersaurus>","From":"Umang Jain ","In-Reply-To":"<164612685751.2188904.6594778238003602197@Monstersaurus>","Content-Type":"text/plain; charset=UTF-8; format=flowed","Content-Transfer-Encoding":"7bit","Subject":"Re: [libcamera-devel] [PATCH 1/2] android: Document the structures\n\tand functions for post-processing","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]