[libcamera-devel] [RFC PATCH 1/2] android: Document the structures and functions for post-processing
Laurent Pinchart
laurent.pinchart at ideasonboard.com
Tue Nov 23 01:52:36 CET 2021
Hi Umang,
Thank you for the patch, it's really useful.
On Fri, Nov 19, 2021 at 06:45:05PM +0530, Umang Jain wrote:
> 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
s/deemed to be complete/that has completed/
> + *
> + * Marks the Camera3RequestDescriptor as 'complete'. This means all the streams
s/Marks/This function marks/
s/This means/It shall be called when/
> + * in the Camera3RequestDescriptor have completed capture (or generated via
s/generated/have been generated/
> + * post-processing) and is ready be sent back to the framework.
s/is ready/the request is ready/
> + *
> + * \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.
I'd be more explicit about the fact that the function loops over the
queue:
* Iterate over the descriptors queue to send completed descriptors back to the
* framework, in the same order as they have been queued. For each complete
* descriptor, populate a locally-scoped camera3_capture_result_t from the
* descriptor, send the capture result back by calling the
* process_capture_result() callback, and remove the descriptor from the queue.
* Stop iterating if the descriptor at the front of the queue is not complete.
> + *
> + * 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
s/This/This function/
s/invoked in/called from/ ?
> + * 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
s/is found to be empty/is then/
s/it is perceived that //
> + * 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
s/Groups/Group/
> + *
> + * A capture request placed to the libcamera HAL can contain multiple streams.
> + * Each stream will have an associated buffer to be filled. StreamBuffer struct
s/StreamBuffer struct/The StreamBuffer structure/
or
s/StreamBuffer struct/StreamBuffer/
> + * tracks this buffer with contextual information which aids in the stream's
> + * generation. The generation of stream will depend on its type (refer
s/of stream/of the stream/
s/refer/refer to the/
> + * CameraStream::Type documentation).
> + *
> + * \var Camera3RequestDescriptor::StreamBuffer::stream
> + * \brief Corresponding pointer to CameraStream
* \brief Pointer to the corresponding 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
s/source/the source/
s/required for/used for/
> + *
> + * \var Camera3RequestDescriptor::StreamBuffer::dstBuffer
> + * \brief Pointer to destination frame buffer required for post-processing
s/destination/the destination/
s/required for/used for/
> + *
> + * \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
s/Post process/Post-process/
s/on an/in an/
> + *
> + * 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
s/queued to/queued to a/
Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> + * 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)
> {
--
Regards,
Laurent Pinchart
More information about the libcamera-devel
mailing list