From 48e393a263d3a20b27f4db9a169f4f1874777e6b Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 5 May 2014 10:16:49 -0300 Subject: [media] DocBook media: improve control section Improve the control section: - Clarify the handling of private controls - Explain the V4L2_CTRL_FLAG_INACTIVE flag - Remove obsolete text regarding missing control event (we have them today) and the incorrect V4L2_CTRL_FLAG_DISABLED reference. - Add a code example on how to enumerate over user controls. Signed-off-by: Hans Verkuil Reviewed-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/controls.xml | 74 +++++++++++++++++++++------- 1 file changed, 55 insertions(+), 19 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 00cf0a719a35..73bae134a3a1 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -13,6 +13,19 @@ correctly with any device. All controls are accessed using an ID value. V4L2 defines several IDs for specific purposes. Drivers can also implement their own custom controls using V4L2_CID_PRIVATE_BASE +The use of V4L2_CID_PRIVATE_BASE +is problematic because different drivers may use the same +V4L2_CID_PRIVATE_BASE ID for different controls. +This makes it hard to programatically set such controls since the meaning +of the control with that ID is driver dependent. In order to resolve this +drivers use unique IDs and the V4L2_CID_PRIVATE_BASE +IDs are mapped to those unique IDs by the kernel. Consider these +V4L2_CID_PRIVATE_BASE IDs as aliases to the real +IDs. +Many applications today still use the V4L2_CID_PRIVATE_BASE +IDs instead of using &VIDIOC-QUERYCTRL; with the V4L2_CTRL_FLAG_NEXT_CTRL +flag to enumerate all IDs, so support for V4L2_CID_PRIVATE_BASE +is still around. and higher values. The pre-defined control IDs have the prefix V4L2_CID_, and are listed in . The ID is used when querying the attributes of @@ -31,25 +44,22 @@ the current video input or output, tuner or modulator, or audio input or output. Different in the sense of other bounds, another default and current value, step size or other menu items. A control with a certain custom ID can also change name and -type. - It will be more convenient for applications if drivers -make use of the V4L2_CTRL_FLAG_DISABLED flag, but -that was never required. - Control values are stored globally, they do not +type. + + If a control is not applicable to the current configuration +of the device (for example, it doesn't apply to the current video input) +drivers set the V4L2_CTRL_FLAG_INACTIVE flag. + + Control values are stored globally, they do not change when switching except to stay within the reported bounds. They also do not change ⪚ when the device is opened or closed, when the tuner radio frequency is changed or generally never without -application request. Since V4L2 specifies no event mechanism, panel -applications intended to cooperate with other panel applications (be -they built into a larger application, as a TV viewer) may need to -regularly poll control values to update their user -interface. - Applications could call an ioctl to request events. -After another process called &VIDIOC-S-CTRL; or another ioctl changing -shared properties the &func-select; function would indicate -readability until any ioctl (querying the properties) is -called. - +application request. + + V4L2 specifies an event mechanism to notify applications +when controls change value (see &VIDIOC-SUBSCRIBE-EVENT;, event +V4L2_EVENT_CTRL), panel applications might want to make +use of that in order to always reflect the correct control value. All controls use machine endianness. @@ -434,8 +444,8 @@ Drivers must implement VIDIOC_QUERYCTRL, controls, VIDIOC_QUERYMENU when it has one or more menu type controls. - - Enumerating all controls + + Enumerating all user controls &v4l2-queryctrl; queryctrl; @@ -500,6 +510,32 @@ for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; + + Enumerating all user controls (alternative) + +memset(&queryctrl, 0, sizeof(queryctrl)); + +queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL; +while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { + if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER) + break; + if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) + continue; + + printf("Control %s\n", queryctrl.name); + + if (queryctrl.type == V4L2_CTRL_TYPE_MENU) + enumerate_menu(); + + queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; +} +if (errno != EINVAL) { + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); +} + + + Changing controls @@ -699,7 +735,7 @@ ID based on a control ID. VIDIOC_QUERYCTRL will fail when used in combination with V4L2_CTRL_FLAG_NEXT_CTRL. In that case the old method of enumerating control should be used (see -1.8). But if it is supported, then it is guaranteed to enumerate over +). But if it is supported, then it is guaranteed to enumerate over all controls, including driver-private controls. -- cgit