aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/video4linux
diff options
context:
space:
mode:
authorHans Verkuil <hans.verkuil@cisco.com>2011-08-26 07:35:59 -0400
committerMauro Carvalho Chehab <mchehab@redhat.com>2011-09-21 09:50:19 -0400
commit882a935c4395a67ea0a6ed6d61531d680190b23f (patch)
tree2c4ef02dff151ef410317c6cfc782b08742b7525 /Documentation/video4linux
parent5626b8c75bc13aa3287c18d49e92edc84fa85b2d (diff)
[media] v4l2-controls.txt: update auto cluster documentation
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>
Diffstat (limited to 'Documentation/video4linux')
-rw-r--r--Documentation/video4linux/v4l2-controls.txt34
1 files changed, 12 insertions, 22 deletions
diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt
index f92ee3053940..26aa0573933e 100644
--- a/Documentation/video4linux/v4l2-controls.txt
+++ b/Documentation/video4linux/v4l2-controls.txt
@@ -495,18 +495,20 @@ Handling autogain/gain-type Controls with Auto Clusters
495 495
496A common type of control cluster is one that handles 'auto-foo/foo'-type 496A common type of control cluster is one that handles 'auto-foo/foo'-type
497controls. Typical examples are autogain/gain, autoexposure/exposure, 497controls. Typical examples are autogain/gain, autoexposure/exposure,
498autowhitebalance/red balance/blue balance. In all cases you have one controls 498autowhitebalance/red balance/blue balance. In all cases you have one control
499that determines whether another control is handled automatically by the hardware, 499that determines whether another control is handled automatically by the hardware,
500or whether it is under manual control from the user. 500or whether it is under manual control from the user.
501 501
502If the cluster is in automatic mode, then the manual controls should be 502If the cluster is in automatic mode, then the manual controls should be
503marked inactive. When the volatile controls are read the g_volatile_ctrl 503marked inactive and volatile. When the volatile controls are read the
504operation should return the value that the hardware's automatic mode set up 504g_volatile_ctrl operation should return the value that the hardware's automatic
505automatically. 505mode set up automatically.
506 506
507If the cluster is put in manual mode, then the manual controls should become 507If the cluster is put in manual mode, then the manual controls should become
508active again and V4L2_CTRL_FLAG_VOLATILE should be ignored (so g_volatile_ctrl 508active again and the volatile flag is cleared (so g_volatile_ctrl is no longer
509is no longer called while in manual mode). 509called while in manual mode). In addition just before switching to manual mode
510the current values as determined by the auto mode are copied as the new manual
511values.
510 512
511Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since 513Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since
512changing that control affects the control flags of the manual controls. 514changing that control affects the control flags of the manual controls.
@@ -520,6 +522,10 @@ void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
520The first two arguments are identical to v4l2_ctrl_cluster. The third argument 522The first two arguments are identical to v4l2_ctrl_cluster. The third argument
521tells the framework which value switches the cluster into manual mode. The 523tells the framework which value switches the cluster into manual mode. The
522last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls. 524last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls.
525If it is false, then the manual controls are never volatile. You would typically
526use that if the hardware does not give you the option to read back to values as
527determined by the auto mode (e.g. if autogain is on, the hardware doesn't allow
528you to obtain the current gain value).
523 529
524The first control of the cluster is assumed to be the 'auto' control. 530The first control of the cluster is assumed to be the 'auto' control.
525 531
@@ -680,16 +686,6 @@ if there are no controls at all.
680count if nothing was done yet. If it is less than count then only the controls 686count if nothing was done yet. If it is less than count then only the controls
681up to error_idx-1 were successfully applied. 687up to error_idx-1 were successfully applied.
682 688
6833) When attempting to read a button control the framework will return -EACCES
684instead of -EINVAL as stated in the spec. It seems to make more sense since
685button controls are write-only controls.
686
6874) Attempting to write to a read-only control will return -EACCES instead of
688-EINVAL as the spec says.
689
6905) The spec does not mention what should happen when you try to set/get a
691control class controls. The framework will return -EACCES.
692
693 689
694Proposals for Extensions 690Proposals for Extensions
695======================== 691========================
@@ -702,9 +698,3 @@ decimal. Useful for e.g. video_mute_yuv.
7022) It is possible to mark in the controls array which controls have been 6982) It is possible to mark in the controls array which controls have been
703successfully written and which failed by for example adding a bit to the 699successfully written and which failed by for example adding a bit to the
704control ID. Not sure if it is worth the effort, though. 700control ID. Not sure if it is worth the effort, though.
705
7063) Trying to set volatile inactive controls should result in -EACCESS.
707
7084) Add a new flag to mark volatile controls. Any application that wants
709to store the state of the controls can then skip volatile inactive controls.
710Currently it is not possible to detect such controls.