Hi Hans, On 01/22/2011 08:06 PM, Hans Verkuil wrote: > Document how to enable/disable controls. > Document the new v4l2_ctrl_auto_cluster function. > Document the practical method of using anonymous structs to 'cluster' > controls instead of using cumbersome control pointer arrays. > > Signed-off-by: Hans Verkuil<hverkuil@xxxxxxxxx> > --- > Documentation/video4linux/v4l2-controls.txt | 94 +++++++++++++++++++++++++++ > 1 files changed, 94 insertions(+), 0 deletions(-) > > diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt > index 881e7f4..78b6674 100644 > --- a/Documentation/video4linux/v4l2-controls.txt > +++ b/Documentation/video4linux/v4l2-controls.txt > @@ -453,6 +453,25 @@ In the example above the following are equivalent for the VOLUME case: > 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 > @@ -475,6 +494,55 @@ 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. > + > +The way these are supposed to be handled is that if you set one of the 'foo' > +controls, then the 'auto-foo' control should automatically switch to manual > +mode, except when you set the 'auto-foo' control at the same time, in which Do "set the 'auto-foo' control at the same time" refer to what is done in a driver? I can't see how this statement could apply to userland. > +case it will depend on the new 'auto-foo' setting whether the new 'foo' value > +is actually ignored or set in the hardware. > + > +The reasoning is that if you explicitly set a manual control, then it makes > +sense to assume that you want to switch to manual mode as well. Whereas if you > +set both the auto and manual control at the same time, then you should follow > +whatever the new value for the auto control is. > + > +Usually the 'foo' control is also volatile, since if the automatic mode is > +enabled, then the reported value for 'foo' is the value that the automatic > +mode has determined is the best at that given time. However, if manual mode > +is selected, then it is just the last stored value. So g_volatile_ctrl should > +only be called when we are in automatic mode. > + > +Finally the V4L2_CTRL_FLAG_UPDATE should also be set for the non-auto controls > +since changing one of them might affect the auto control. > + > +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 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: > + > +- the right flags are set. > +- when a 'foo' control is set explicitly the 'auto-foo' control is set to > + the manual mode before s_ctrl is called. So it means that, if it is required to set multiple foo controls (atomically) before disabling auto-foo control, the control clusters should not be used? Regards, Sylwester -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html