[RFC,v1,13/23] libcamera: camera: Introduce metadataAvailable signal

23494 diff mbox series

From: Jacopo Mondi <jacopo.mondi@ideasonboard.com>

Add a new signal to the Camera class that allows applications to
receive notifications for early completion of metadata results.

To avoid expensive copies of the metadata results the signal
transports the ids of the metadata keys that are ready. Applications
can use these ids to access the metadata results from
Request::metadata().

The signal is an opt-in feature for applications and the sum of
all metadata results notified through this signal is available
in Request::metadata() at request completion time.

Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
[Use `MetadataList::Diff`, change documentation accordingly.]
Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
---
Original: https://patchwork.libcamera.org/patch/22227/
---
 include/libcamera/camera.h |  1 +
 src/libcamera/camera.cpp   | 54 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

Hi Barnabás

On Fri, Jun 06, 2025 at 06:41:46PM +0200, Barnabás Pőcze wrote:
> From: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
>
> Add a new signal to the Camera class that allows applications to
> receive notifications for early completion of metadata results.
>
> To avoid expensive copies of the metadata results the signal
> transports the ids of the metadata keys that are ready. Applications
> can use these ids to access the metadata results from
> Request::metadata().
>
> The signal is an opt-in feature for applications and the sum of
> all metadata results notified through this signal is available
> in Request::metadata() at request completion time.

This paragraph doesn't apply anymore ;)

>
> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> [Use `MetadataList::Diff`, change documentation accordingly.]
> Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> ---
> Original: https://patchwork.libcamera.org/patch/22227/
> ---
>  include/libcamera/camera.h |  1 +
>  src/libcamera/camera.cpp   | 54 ++++++++++++++++++++++++++++++++++++++
>  2 files changed, 55 insertions(+)
>
> diff --git a/include/libcamera/camera.h b/include/libcamera/camera.h
> index 94cee7bd8..bf5623ddf 100644
> --- a/include/libcamera/camera.h
> +++ b/include/libcamera/camera.h
> @@ -122,6 +122,7 @@ public:
>
>  	const std::string &id() const;
>
> +	Signal<Request *, MetadataList::Diff> metadataAvailable;
>  	Signal<Request *, FrameBuffer *> bufferCompleted;
>  	Signal<Request *> requestCompleted;
>  	Signal<> disconnected;
> diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp
> index 31f5ad94b..2c87c3274 100644
> --- a/src/libcamera/camera.cpp
> +++ b/src/libcamera/camera.cpp
> @@ -902,6 +902,60 @@ const std::string &Camera::id() const
>  	return _d()->id_;
>  }
>
> +/**
> + * \var Camera::metadataAvailable
> + * \brief Signal emitted when metadata for a request is available
> + *
> + * The metadataAvailable signal notifies applications about the availability
> + * of metadata for a request before the request completes.
> + *
> + * As metadata results could be large in size, the signal transports only a view
> + * object via which the newly completed metadata items can be accessed. Similarly
> + * to the metadata list itself, this object is thread-safe, and can be sent to other
> + * threads for deferred processing. The view object is valid until the request is
> + * destroyed or reused, whichever happens first.
> + *
> + * Applications can access the value of the newly available metadata results as follows:
> + *
> + * \code
> +
> +	void metadataAvailableHandler(Request *request, MetadataList::Diff update)
> +	{
> +		// The object can be iterated...
> +		for (auto &&[id, data] : update) {
> +			// `id` is the numeric identifier
> +			// `data` is a `ControlValueView` object
> +		}
> +
> +		// ...or individual items can be looked up.
> +		if (auto x = update.get(controls::SensorTimestamp)) {
> +			// `SensorTimestamp` will only be found if it is part of this
> +			// particular update; metadata items completed earlier will
> +			// not be found.
> +		}
> +	}
> +   \endcode
> + *
> + * This signal is emitted multiple times for the same request, it is in fact
> + * emitted by the framework every time a new metadata list is made available

s/a new metadata list is/new metadata are/

?

> + * by the Camera to the application.
> + *
> + * The sum of all metadata lists reported through this signal is equal to

s/lists// ?

> + * Request::metadata() list when the Request completes.
> + *
> + * Application can opt-in to handle this signal to receive fast notifications
> + * of metadata availability or can equally access the full metadata list
> + * at Request complete time through Request::metadata() if they have no interest
> + * in early metadata notification.
> + *
> + * \note The received MetadataList::Diff object is merely a view, it is only valid until
> + *       the associated Request is destroyed or \ref Request::reuse() "reused". However,
> + *       during its valid lifetime, an application is free to create copies and access the
> + *       completed metadata items from separate thread by iteration or MetadataList::Diff::get().
> + *
> + * \sa ControlValueView
      \sa MetadataList
      ?

Just minors
Reviewed-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>

Thanks
  j

> + */
> +
>  /**
>   * \var Camera::bufferCompleted
>   * \brief Signal emitted when a buffer for a request queued to the camera has
> --
> 2.49.0
>

Hi

2025. 06. 19. 13:23 keltezéssel, Jacopo Mondi írta:
> Hi Barnabás
> 
> On Fri, Jun 06, 2025 at 06:41:46PM +0200, Barnabás Pőcze wrote:
>> From: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
>>
>> Add a new signal to the Camera class that allows applications to
>> receive notifications for early completion of metadata results.
>>
>> To avoid expensive copies of the metadata results the signal
>> transports the ids of the metadata keys that are ready. Applications
>> can use these ids to access the metadata results from
>> Request::metadata().
>>
>> The signal is an opt-in feature for applications and the sum of
>> all metadata results notified through this signal is available
>> in Request::metadata() at request completion time.
> 
> This paragraph doesn't apply anymore ;)

Why not? I think it still true. The paragraph above this is
indeed not true anymore. I will change it to:

   To avoid expensive copies of the metadata results the signal
   transports a view object of metadata items that are ready.


> 
>>
>> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
>> [Use `MetadataList::Diff`, change documentation accordingly.]
>> Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
>> ---
>> Original: https://patchwork.libcamera.org/patch/22227/
>> ---
>>   include/libcamera/camera.h |  1 +
>>   src/libcamera/camera.cpp   | 54 ++++++++++++++++++++++++++++++++++++++
>>   2 files changed, 55 insertions(+)
>>
>> diff --git a/include/libcamera/camera.h b/include/libcamera/camera.h
>> index 94cee7bd8..bf5623ddf 100644
>> --- a/include/libcamera/camera.h
>> +++ b/include/libcamera/camera.h
>> @@ -122,6 +122,7 @@ public:
>>
>>   	const std::string &id() const;
>>
>> +	Signal<Request *, MetadataList::Diff> metadataAvailable;
>>   	Signal<Request *, FrameBuffer *> bufferCompleted;
>>   	Signal<Request *> requestCompleted;
>>   	Signal<> disconnected;
>> diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp
>> index 31f5ad94b..2c87c3274 100644
>> --- a/src/libcamera/camera.cpp
>> +++ b/src/libcamera/camera.cpp
>> @@ -902,6 +902,60 @@ const std::string &Camera::id() const
>>   	return _d()->id_;
>>   }
>>
>> +/**
>> + * \var Camera::metadataAvailable
>> + * \brief Signal emitted when metadata for a request is available
>> + *
>> + * The metadataAvailable signal notifies applications about the availability
>> + * of metadata for a request before the request completes.
>> + *
>> + * As metadata results could be large in size, the signal transports only a view
>> + * object via which the newly completed metadata items can be accessed. Similarly
>> + * to the metadata list itself, this object is thread-safe, and can be sent to other
>> + * threads for deferred processing. The view object is valid until the request is
>> + * destroyed or reused, whichever happens first.
>> + *
>> + * Applications can access the value of the newly available metadata results as follows:
>> + *
>> + * \code
>> +
>> +	void metadataAvailableHandler(Request *request, MetadataList::Diff update)
>> +	{
>> +		// The object can be iterated...
>> +		for (auto &&[id, data] : update) {
>> +			// `id` is the numeric identifier
>> +			// `data` is a `ControlValueView` object
>> +		}
>> +
>> +		// ...or individual items can be looked up.
>> +		if (auto x = update.get(controls::SensorTimestamp)) {
>> +			// `SensorTimestamp` will only be found if it is part of this
>> +			// particular update; metadata items completed earlier will
>> +			// not be found.
>> +		}
>> +	}
>> +   \endcode
>> + *
>> + * This signal is emitted multiple times for the same request, it is in fact
>> + * emitted by the framework every time a new metadata list is made available
> 
> s/a new metadata list is/new metadata are/

I changed it to "a new set of metadata"


> 
> ?
> 
>> + * by the Camera to the application.
>> + *
>> + * The sum of all metadata lists reported through this signal is equal to
> 
> s/lists// ?

Done.


> 
>> + * Request::metadata() list when the Request completes.
>> + *
>> + * Application can opt-in to handle this signal to receive fast notifications
>> + * of metadata availability or can equally access the full metadata list
>> + * at Request complete time through Request::metadata() if they have no interest
>> + * in early metadata notification.
>> + *
>> + * \note The received MetadataList::Diff object is merely a view, it is only valid until
>> + *       the associated Request is destroyed or \ref Request::reuse() "reused". However,
>> + *       during its valid lifetime, an application is free to create copies and access the
>> + *       completed metadata items from separate thread by iteration or MetadataList::Diff::get().
>> + *
>> + * \sa ControlValueView
>        \sa MetadataList
>        ?
> 
> Just minors
> Reviewed-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> 
> Thanks
>    j
> 
>> + */
>> +
>>   /**
>>    * \var Camera::bufferCompleted
>>    * \brief Signal emitted when a buffer for a request queued to the camera has
>> --
>> 2.49.0
>>


Regards,
Barnabás Pőcze

Hi Barnabás

On Thu, Jun 19, 2025 at 02:30:53PM +0200, Barnabás Pőcze wrote:
> Hi
>
> 2025. 06. 19. 13:23 keltezéssel, Jacopo Mondi írta:
> > Hi Barnabás
> >
> > On Fri, Jun 06, 2025 at 06:41:46PM +0200, Barnabás Pőcze wrote:
> > > From: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> > >
> > > Add a new signal to the Camera class that allows applications to
> > > receive notifications for early completion of metadata results.
> > >
> > > To avoid expensive copies of the metadata results the signal
> > > transports the ids of the metadata keys that are ready. Applications
> > > can use these ids to access the metadata results from
> > > Request::metadata().
> > >
> > > The signal is an opt-in feature for applications and the sum of
> > > all metadata results notified through this signal is available
> > > in Request::metadata() at request completion time.
> >
> > This paragraph doesn't apply anymore ;)
>
> Why not? I think it still true. The paragraph above this is
> indeed not true anymore. I will change it to:
>
>   To avoid expensive copies of the metadata results the signal
>   transports a view object of metadata items that are ready.
>

Sorry, I went a paragraph to low.

I meant

> > > To avoid expensive copies of the metadata results the signal
> > > transports the ids of the metadata keys that are ready. Applications
> > > can use these ids to access the metadata results from
> > > Request::metadata().

This doesn't apply, as my original patch transported ids, while we now
have a proper object.

Your proposal of

>   To avoid expensive copies of the metadata results the signal
>   transports a view object of metadata items that are ready.

sounds good


>
> >
> > >
> > > Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> > > [Use `MetadataList::Diff`, change documentation accordingly.]
> > > Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> > > ---
> > > Original: https://patchwork.libcamera.org/patch/22227/
> > > ---
> > >   include/libcamera/camera.h |  1 +
> > >   src/libcamera/camera.cpp   | 54 ++++++++++++++++++++++++++++++++++++++
> > >   2 files changed, 55 insertions(+)
> > >
> > > diff --git a/include/libcamera/camera.h b/include/libcamera/camera.h
> > > index 94cee7bd8..bf5623ddf 100644
> > > --- a/include/libcamera/camera.h
> > > +++ b/include/libcamera/camera.h
> > > @@ -122,6 +122,7 @@ public:
> > >
> > >   	const std::string &id() const;
> > >
> > > +	Signal<Request *, MetadataList::Diff> metadataAvailable;
> > >   	Signal<Request *, FrameBuffer *> bufferCompleted;
> > >   	Signal<Request *> requestCompleted;
> > >   	Signal<> disconnected;
> > > diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp
> > > index 31f5ad94b..2c87c3274 100644
> > > --- a/src/libcamera/camera.cpp
> > > +++ b/src/libcamera/camera.cpp
> > > @@ -902,6 +902,60 @@ const std::string &Camera::id() const
> > >   	return _d()->id_;
> > >   }
> > >
> > > +/**
> > > + * \var Camera::metadataAvailable
> > > + * \brief Signal emitted when metadata for a request is available
> > > + *
> > > + * The metadataAvailable signal notifies applications about the availability
> > > + * of metadata for a request before the request completes.
> > > + *
> > > + * As metadata results could be large in size, the signal transports only a view
> > > + * object via which the newly completed metadata items can be accessed. Similarly
> > > + * to the metadata list itself, this object is thread-safe, and can be sent to other
> > > + * threads for deferred processing. The view object is valid until the request is
> > > + * destroyed or reused, whichever happens first.
> > > + *
> > > + * Applications can access the value of the newly available metadata results as follows:
> > > + *
> > > + * \code
> > > +
> > > +	void metadataAvailableHandler(Request *request, MetadataList::Diff update)
> > > +	{
> > > +		// The object can be iterated...
> > > +		for (auto &&[id, data] : update) {
> > > +			// `id` is the numeric identifier
> > > +			// `data` is a `ControlValueView` object
> > > +		}
> > > +
> > > +		// ...or individual items can be looked up.
> > > +		if (auto x = update.get(controls::SensorTimestamp)) {
> > > +			// `SensorTimestamp` will only be found if it is part of this
> > > +			// particular update; metadata items completed earlier will
> > > +			// not be found.
> > > +		}
> > > +	}
> > > +   \endcode
> > > + *
> > > + * This signal is emitted multiple times for the same request, it is in fact
> > > + * emitted by the framework every time a new metadata list is made available
> >
> > s/a new metadata list is/new metadata are/
>
> I changed it to "a new set of metadata"
>
>
> >
> > ?
> >
> > > + * by the Camera to the application.
> > > + *
> > > + * The sum of all metadata lists reported through this signal is equal to
> >
> > s/lists// ?
>
> Done.
>
>
> >
> > > + * Request::metadata() list when the Request completes.
> > > + *
> > > + * Application can opt-in to handle this signal to receive fast notifications
> > > + * of metadata availability or can equally access the full metadata list
> > > + * at Request complete time through Request::metadata() if they have no interest
> > > + * in early metadata notification.
> > > + *
> > > + * \note The received MetadataList::Diff object is merely a view, it is only valid until
> > > + *       the associated Request is destroyed or \ref Request::reuse() "reused". However,
> > > + *       during its valid lifetime, an application is free to create copies and access the
> > > + *       completed metadata items from separate thread by iteration or MetadataList::Diff::get().
> > > + *
> > > + * \sa ControlValueView
> >        \sa MetadataList
> >        ?
> >
> > Just minors
> > Reviewed-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> >
> > Thanks
> >    j
> >
> > > + */
> > > +
> > >   /**
> > >    * \var Camera::bufferCompleted
> > >    * \brief Signal emitted when a buffer for a request queued to the camera has
> > > --
> > > 2.49.0
> > >
>
>
> Regards,
> Barnabás Pőcze