| Message ID | 20211119131506.382462-2-umang.jain@ideasonboard.com |
|---|---|
| State | Changes Requested |
| Headers | show |
| Series |
|
| Related | show |
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@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@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) > {
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) {
Specifically document: - CameraDevice::sendCaptureResults() - CameraDevice::completeDescriptor() - CameraDevice::streamProcessingComplete() - CameraStream::PostProcessorWorker class - Camera3RequestDescriptor::StreamBuffer structure Signed-off-by: Umang Jain <umang.jain@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(+)