[media] Documentation: Improve cluster documentation and document the new autoclusters

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

[media] Documentation: Improve cluster documentation and document the new autoclusters
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Hans Verkuil · Mauro Carvalho Chehab
1 parent 72d877cac0
Showing 1 changed file with 56 additions and 0 deletions Side-by-side Diff
Documentation/video4linux/v4l2-controls.txt
@@ -450,6 +450,25 @@
 	ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]
 	ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]
  
+In practice using cluster arrays like this becomes very tiresome. So instead
+the following equivalent method is used:
+
+	struct {
+		/* audio cluster */
+		struct v4l2_ctrl *volume;
+		struct v4l2_ctrl *mute;
+	};
+
+The anonymous struct is used to clearly 'cluster' these two control pointers,
+but it serves no other purpose. The effect is the same as creating an
+array with two control pointers. So you can just do:
+
+	state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
+	state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
+	v4l2_ctrl_cluster(2, &state->volume);
+
+And in foo_s_ctrl you can use these pointers directly: state->mute->val.
+
 Note that controls in a cluster may be NULL. For example, if for some
 reason mute was never added (because the hardware doesn't support that
 particular feature), then mute will be NULL. So in that case we have a
@@ -470,6 +489,43 @@
 controls, then the 'is_new' flag would be 1 for both controls.
  
 The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup().
+
+
+Handling autogain/gain-type Controls with Auto Clusters
+=======================================================
+
+A common type of control cluster is one that handles 'auto-foo/foo'-type
+controls. Typical examples are autogain/gain, autoexposure/exposure,
+autowhitebalance/red balance/blue balance. In all cases you have one controls
+that determines whether another control is handled automatically by the hardware,
+or whether it is under manual control from the user.
+
+If the cluster is in automatic mode, then the manual controls should be
+marked inactive. When the volatile controls are read the g_volatile_ctrl
+operation should return the value that the hardware's automatic mode set up
+automatically.
+
+If the cluster is put in manual mode, then the manual controls should become
+active again and the is_volatile flag should be ignored (so g_volatile_ctrl is
+no longer called while in manual mode).
+
+Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since
+changing that control affects the control flags of the manual controls.
+
+In order to simplify this a special variation of v4l2_ctrl_cluster was
+introduced:
+
+void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
+			u8 manual_val, bool set_volatile);
+
+The first two arguments are identical to v4l2_ctrl_cluster. The third argument
+tells the framework which value switches the cluster into manual mode. The
+last argument will optionally set the is_volatile flag for the non-auto controls.
+
+The first control of the cluster is assumed to be the 'auto' control.
+
+Using this function will ensure that you don't need to handle all the complex
+flag and volatile handling.
  
  
 VIDIOC_LOG_STATUS Support
...	...	@@ -450,6 +450,25 @@
450	450	ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]
451	451	ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]
452	452
	453	+In practice using cluster arrays like this becomes very tiresome. So instead
	454	+the following equivalent method is used:
	455	+
	456	+ struct {
	457	+ /* audio cluster */
	458	+ struct v4l2_ctrl *volume;
	459	+ struct v4l2_ctrl *mute;
	460	+ };
	461	+
	462	+The anonymous struct is used to clearly 'cluster' these two control pointers,
	463	+but it serves no other purpose. The effect is the same as creating an
	464	+array with two control pointers. So you can just do:
	465	+
	466	+ state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
	467	+ state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
	468	+ v4l2_ctrl_cluster(2, &state->volume);
	469	+
	470	+And in foo_s_ctrl you can use these pointers directly: state->mute->val.
	471	+
453	472	Note that controls in a cluster may be NULL. For example, if for some
454	473	reason mute was never added (because the hardware doesn't support that
455	474	particular feature), then mute will be NULL. So in that case we have a
...	...	@@ -470,6 +489,43 @@
470	489	controls, then the 'is_new' flag would be 1 for both controls.
471	490
472	491	The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup().
	492	+
	493	+
	494	+Handling autogain/gain-type Controls with Auto Clusters
	495	+=======================================================
	496	+
	497	+A common type of control cluster is one that handles 'auto-foo/foo'-type
	498	+controls. Typical examples are autogain/gain, autoexposure/exposure,
	499	+autowhitebalance/red balance/blue balance. In all cases you have one controls
	500	+that determines whether another control is handled automatically by the hardware,
	501	+or whether it is under manual control from the user.
	502	+
	503	+If the cluster is in automatic mode, then the manual controls should be
	504	+marked inactive. When the volatile controls are read the g_volatile_ctrl
	505	+operation should return the value that the hardware's automatic mode set up
	506	+automatically.
	507	+
	508	+If the cluster is put in manual mode, then the manual controls should become
	509	+active again and the is_volatile flag should be ignored (so g_volatile_ctrl is
	510	+no longer called while in manual mode).
	511	+
	512	+Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since
	513	+changing that control affects the control flags of the manual controls.
	514	+
	515	+In order to simplify this a special variation of v4l2_ctrl_cluster was
	516	+introduced:
	517	+
	518	+void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
	519	+ u8 manual_val, bool set_volatile);
	520	+
	521	+The first two arguments are identical to v4l2_ctrl_cluster. The third argument
	522	+tells the framework which value switches the cluster into manual mode. The
	523	+last argument will optionally set the is_volatile flag for the non-auto controls.
	524	+
	525	+The first control of the cluster is assumed to be the 'auto' control.
	526	+
	527	+Using this function will ensure that you don't need to handle all the complex
	528	+flag and volatile handling.
473	529
474	530
475	531	VIDIOC_LOG_STATUS Support