diff options
author | Hans Verkuil <hans.verkuil@cisco.com> | 2011-08-26 07:35:59 -0400 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@redhat.com> | 2011-09-21 09:50:19 -0400 |
commit | 882a935c4395a67ea0a6ed6d61531d680190b23f (patch) | |
tree | 2c4ef02dff151ef410317c6cfc782b08742b7525 /Documentation | |
parent | 5626b8c75bc13aa3287c18d49e92edc84fa85b2d (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')
-rw-r--r-- | Documentation/video4linux/v4l2-controls.txt | 34 |
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 | ||
496 | A common type of control cluster is one that handles 'auto-foo/foo'-type | 496 | A common type of control cluster is one that handles 'auto-foo/foo'-type |
497 | controls. Typical examples are autogain/gain, autoexposure/exposure, | 497 | controls. Typical examples are autogain/gain, autoexposure/exposure, |
498 | autowhitebalance/red balance/blue balance. In all cases you have one controls | 498 | autowhitebalance/red balance/blue balance. In all cases you have one control |
499 | that determines whether another control is handled automatically by the hardware, | 499 | that determines whether another control is handled automatically by the hardware, |
500 | or whether it is under manual control from the user. | 500 | or whether it is under manual control from the user. |
501 | 501 | ||
502 | If the cluster is in automatic mode, then the manual controls should be | 502 | If the cluster is in automatic mode, then the manual controls should be |
503 | marked inactive. When the volatile controls are read the g_volatile_ctrl | 503 | marked inactive and volatile. When the volatile controls are read the |
504 | operation should return the value that the hardware's automatic mode set up | 504 | g_volatile_ctrl operation should return the value that the hardware's automatic |
505 | automatically. | 505 | mode set up automatically. |
506 | 506 | ||
507 | If the cluster is put in manual mode, then the manual controls should become | 507 | If the cluster is put in manual mode, then the manual controls should become |
508 | active again and V4L2_CTRL_FLAG_VOLATILE should be ignored (so g_volatile_ctrl | 508 | active again and the volatile flag is cleared (so g_volatile_ctrl is no longer |
509 | is no longer called while in manual mode). | 509 | called while in manual mode). In addition just before switching to manual mode |
510 | the current values as determined by the auto mode are copied as the new manual | ||
511 | values. | ||
510 | 512 | ||
511 | Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since | 513 | Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since |
512 | changing that control affects the control flags of the manual controls. | 514 | changing 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, | |||
520 | The first two arguments are identical to v4l2_ctrl_cluster. The third argument | 522 | The first two arguments are identical to v4l2_ctrl_cluster. The third argument |
521 | tells the framework which value switches the cluster into manual mode. The | 523 | tells the framework which value switches the cluster into manual mode. The |
522 | last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls. | 524 | last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls. |
525 | If it is false, then the manual controls are never volatile. You would typically | ||
526 | use that if the hardware does not give you the option to read back to values as | ||
527 | determined by the auto mode (e.g. if autogain is on, the hardware doesn't allow | ||
528 | you to obtain the current gain value). | ||
523 | 529 | ||
524 | The first control of the cluster is assumed to be the 'auto' control. | 530 | The 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. | |||
680 | count if nothing was done yet. If it is less than count then only the controls | 686 | count if nothing was done yet. If it is less than count then only the controls |
681 | up to error_idx-1 were successfully applied. | 687 | up to error_idx-1 were successfully applied. |
682 | 688 | ||
683 | 3) When attempting to read a button control the framework will return -EACCES | ||
684 | instead of -EINVAL as stated in the spec. It seems to make more sense since | ||
685 | button controls are write-only controls. | ||
686 | |||
687 | 4) Attempting to write to a read-only control will return -EACCES instead of | ||
688 | -EINVAL as the spec says. | ||
689 | |||
690 | 5) The spec does not mention what should happen when you try to set/get a | ||
691 | control class controls. The framework will return -EACCES. | ||
692 | |||
693 | 689 | ||
694 | Proposals for Extensions | 690 | Proposals for Extensions |
695 | ======================== | 691 | ======================== |
@@ -702,9 +698,3 @@ decimal. Useful for e.g. video_mute_yuv. | |||
702 | 2) It is possible to mark in the controls array which controls have been | 698 | 2) It is possible to mark in the controls array which controls have been |
703 | successfully written and which failed by for example adding a bit to the | 699 | successfully written and which failed by for example adding a bit to the |
704 | control ID. Not sure if it is worth the effort, though. | 700 | control ID. Not sure if it is worth the effort, though. |
705 | |||
706 | 3) Trying to set volatile inactive controls should result in -EACCESS. | ||
707 | |||
708 | 4) Add a new flag to mark volatile controls. Any application that wants | ||
709 | to store the state of the controls can then skip volatile inactive controls. | ||
710 | Currently it is not possible to detect such controls. | ||