[media] v4l2-ctrls: implement new volatile autocluster scheme

The problem tackled in this patch is how to handle volatile autoclusters
correctly. A volatile autocluster is a cluster of related controls where one
control is the control that toggles between manual and auto mode and the other
controls are the values for the manual mode. For example autogain and gain,
autoexposure and exposure, etc.

If the hardware lets you read out the automatically calculated manual values
while in automode, then those manual controls should be marked volatile.

gain value as calculated by the autogain circuitry, then you would mark the
gain control as volatile (i.e. continuously changing).

The question in such use cases is what to do when switching from the auto
mode to the manual mode. Should we switch to the last set manual values or
should the volatile values be copied and used as the initial manual values.

For example: suppose the mode is manual gain and gain is set to 5. Then
autogain is turned on and the gain is set by the hardware to 2. Finally
the user switches back to manual gain. What should the gain be? 2 or 5?

After a long discussion the decisions was made to keep the last value as
calculated by the auto mode (so 2 in the example above).

The reason is that webcams that do such things will adapt themselves to
the current light conditions and when you switch back to manual mode you
expect that you keep the same picture. If you would switch back to old
manual values, then that would give you a suddenly different picture,
which is jarring for the user.

Additionally, this would be difficult to implement in applications that
store and restore the control values at application exit and start.

If you want to keep the old manual values when you switch from auto to
manual, then there would have to be a way for applications to get hold
of those old values while in auto mode, but there isn't.

So this patch will do all the heavy lifting in v4l2-ctrls.c: if you go
from auto mode to manual mode and the manual controls are volatile, then
g_volatile_ctrl will be called to get the current values for the manual
controls before switching to manual mode.

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Acked-by: Hans de Goede <hdegoede@redhat.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

1 files changed, 3 insertions, 0 deletions

diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
index bd6a4a7370d..eeb3df63714 100644
--- a/include/media/v4l2-ctrls.h
+++ b/include/media/v4l2-ctrls.h
@@ -69,6 +69,8 @@ struct v4l2_ctrl_ops {
   *		members are in 'automatic' mode or 'manual' mode. This is
   *		used for autogain/gain type clusters. Drivers should never
   *		set this flag directly.
+  * @has_volatiles: If set, then one or more members of the cluster are volatile.
+  *		Drivers should never touch this flag.
   * @manual_mode_value: If the is_auto flag is set, then this is the value
   *		of the auto control that determines if that control is in
   *		manual mode. So if the value of the auto control equals this
@@ -115,6 +117,7 @@ struct v4l2_ctrl {
 	unsigned int is_new:1;
 	unsigned int is_private:1;
 	unsigned int is_auto:1;
+	unsigned int has_volatiles:1;
 	unsigned int manual_mode_value:8;
 
 	const struct v4l2_ctrl_ops *ops;