[PATCH v3] libcamera: controls: Add policy parameter to ControlList::merge()

[Jacopo Mondi]

On Thu, Mar 07, 2024 at 11:27:38AM +0100, Stefan Klug wrote:
> This is useful in many cases although not included in the stl.
>
> Note: This is an ABI incompatible change.
>
> Signed-off-by: Stefan Klug <stefan.klug at ideasonboard.com>
> Reviewed-by: Umang Jain <umang.jain at ideasonboard.com>
> ---
> Changes in v2:
>  - Added unittest and fixes doxygen docs.
> Changes in v3:
>  - Replace boolean param by enum for better readability
>  - Added note on ABI breakage
>
>  include/libcamera/controls.h   |  7 ++++-
>  src/libcamera/controls.cpp     | 20 ++++++++++++--
>  test/controls/control_list.cpp | 50 ++++++++++++++++++++++++++++++++++
>  3 files changed, 73 insertions(+), 4 deletions(-)
>
> diff --git a/include/libcamera/controls.h b/include/libcamera/controls.h
> index cf942055..82b95599 100644
> --- a/include/libcamera/controls.h
> +++ b/include/libcamera/controls.h
> @@ -352,6 +352,11 @@ private:
>  	using ControlListMap = std::unordered_map<unsigned int, ControlValue>;
>
>  public:
> +	enum class MergePolicy {
> +		KeepExisting = 0,
> +		OverwriteExisting,
> +	};
> +
>  	ControlList();
>  	ControlList(const ControlIdMap &idmap, const ControlValidator *validator = nullptr);
>  	ControlList(const ControlInfoMap &infoMap, const ControlValidator *validator = nullptr);
> @@ -368,7 +373,7 @@ public:
>  	std::size_t size() const { return controls_.size(); }
>
>  	void clear() { controls_.clear(); }
> -	void merge(const ControlList &source);
> +	void merge(const ControlList &source, MergePolicy policy = MergePolicy::KeepExisting);
>
>  	bool contains(unsigned int id) const;
>
> diff --git a/src/libcamera/controls.cpp b/src/libcamera/controls.cpp
> index b808116c..16d3547c 100644
> --- a/src/libcamera/controls.cpp
> +++ b/src/libcamera/controls.cpp
> @@ -907,13 +907,27 @@ ControlList::ControlList(const ControlInfoMap &infoMap,
>   * \brief Removes all controls from the list
>   */
>
> +/**
> + * \enum ControlList::MergePolicy
> + * \brief The policy used by the merge function
> + *
> + * \var ControlList::MergePolicy::KeepExisting
> + * \brief Existing controls in the target list are kept
> + *
> + * \var ControlList::MergePolicy::OverwriteExisting
> + * \brief Existing controls in the target list are updated
> + */
> +
>  /**
>   * \brief Merge the \a source into the ControlList
>   * \param[in] source The ControlList to merge into this object
> + * \param[in] policy Controls if existing elements in *this shall be
> + * overwritten
>   *
>   * Merging two control lists copies elements from the \a source and inserts
>   * them in *this. If the \a source contains elements whose key is already
> - * present in *this, then those elements are not overwritten.
> + * present in *this, then those elements are only overwritten if
> + * \a policy is MergePolicy::OverwriteExisting.
>   *
>   * Only control lists created from the same ControlIdMap or ControlInfoMap may
>   * be merged. Attempting to do otherwise results in undefined behaviour.
> @@ -921,7 +935,7 @@ ControlList::ControlList(const ControlInfoMap &infoMap,
>   * \todo Reimplement or implement an overloaded version which internally uses
>   * std::unordered_map::merge() and accepts a non-const argument.
>   */
> -void ControlList::merge(const ControlList &source)
> +void ControlList::merge(const ControlList &source, MergePolicy policy)
>  {
>  	/**
>  	 * \todo ASSERT that the current and source ControlList are derived
> @@ -936,7 +950,7 @@ void ControlList::merge(const ControlList &source)
>  	 */
>
>  	for (const auto &ctrl : source) {
> -		if (contains(ctrl.first)) {
> +		if (policy == MergePolicy::KeepExisting && contains(ctrl.first)) {
>  			const ControlId *id = idmap_->at(ctrl.first);
>  			LOG(Controls, Warning)
>  				<< "Control " << id->name() << " not overwritten";
> diff --git a/test/controls/control_list.cpp b/test/controls/control_list.cpp
> index c03f230e..e86df49f 100644
> --- a/test/controls/control_list.cpp
> +++ b/test/controls/control_list.cpp
> @@ -196,6 +196,56 @@ protected:
>  			return TestFail;
>  		}
>
> +		/*
> +		 * Create two lists with overlapping controls. Merge them with
> +		 * overwriteExisting = true, verifying that the existing control
> +		 * values *get* overwritten.
> +		 */
> +		mergeList.clear();
> +		mergeList.set(controls::Brightness, 0.7f);
> +		mergeList.set(controls::Saturation, 0.4f);
> +
> +		list.clear();
> +		list.set(controls::Brightness, 0.5f);
> +		list.set(controls::Contrast, 1.1f);
> +
> +		mergeList.merge(list, ControlList::MergePolicy::OverwriteExisting);
> +		if (mergeList.size() != 3) {
> +			cout << "Merged list should contain three elements" << endl;
> +			return TestFail;
> +		}
> +
> +		if (list.size() != 2) {
> +			cout << "The list to merge should contain two elements"
> +			     << endl;
> +			return TestFail;
> +		}
> +
> +		if (!mergeList.get(controls::Brightness) ||
> +		    !mergeList.get(controls::Contrast) ||
> +		    !mergeList.get(controls::Saturation)) {
> +			cout << "Merged list does not contain all controls" << endl;
> +			return TestFail;
> +		}
> +
> +		if (mergeList.get(controls::Brightness) != 0.5f) {
> +			cout << "Brightness control value did not change after merging lists"
> +			     << endl;
> +			return TestFail;
> +		}
> +
> +		if (mergeList.get(controls::Contrast) != 1.1f) {
> +			cout << "Contrast control value did not change after merging lists"

I guess the error is that the "control value -changed-" as you're
expecting it to be 1.1f which is the value you have initialized it to

> +			     << endl;
> +			return TestFail;
> +		}
> +
> +		if (mergeList.get(controls::Saturation) != 0.4f) {
> +			cout << "Saturation control value changed after merging lists"

Ah see, this is right

> +			     << endl;
> +			return TestFail;
> +		}
> +
>  		return TestPass;

Nit aparts

Reviewed-by: Jacopo Mondi <jacopo.mondi at ideasonboard.com>

Thanks
  j

>  	}
>  };
> --
> 2.40.1
>