1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 2
3 .. _extended-controls: 3 .. _extended-controls:
4 4
5 ********************* 5 *********************
6 Extended Controls API 6 Extended Controls API
7 ********************* 7 *********************
8 8
9 9
10 Introduction 10 Introduction
11 ============ 11 ============
12 12
13 The control mechanism as originally designed w 13 The control mechanism as originally designed was meant to be used for
14 user settings (brightness, saturation, etc). H 14 user settings (brightness, saturation, etc). However, it turned out to
15 be a very useful model for implementing more c 15 be a very useful model for implementing more complicated driver APIs
16 where each driver implements only a subset of 16 where each driver implements only a subset of a larger API.
17 17
18 The MPEG encoding API was the driving force be 18 The MPEG encoding API was the driving force behind designing and
19 implementing this extended control mechanism: 19 implementing this extended control mechanism: the MPEG standard is quite
20 large and the currently supported hardware MPE 20 large and the currently supported hardware MPEG encoders each only
21 implement a subset of this standard. Further m 21 implement a subset of this standard. Further more, many parameters
22 relating to how the video is encoded into an M 22 relating to how the video is encoded into an MPEG stream are specific to
23 the MPEG encoding chip since the MPEG standard 23 the MPEG encoding chip since the MPEG standard only defines the format
24 of the resulting MPEG stream, not how the vide 24 of the resulting MPEG stream, not how the video is actually encoded into
25 that format. 25 that format.
26 26
27 Unfortunately, the original control API lacked 27 Unfortunately, the original control API lacked some features needed for
28 these new uses and so it was extended into the 28 these new uses and so it was extended into the (not terribly originally
29 named) extended control API. 29 named) extended control API.
30 30
31 Even though the MPEG encoding API was the firs 31 Even though the MPEG encoding API was the first effort to use the
32 Extended Control API, nowadays there are also 32 Extended Control API, nowadays there are also other classes of Extended
33 Controls, such as Camera Controls and FM Trans 33 Controls, such as Camera Controls and FM Transmitter Controls. The
34 Extended Controls API as well as all Extended 34 Extended Controls API as well as all Extended Controls classes are
35 described in the following text. 35 described in the following text.
36 36
37 37
38 The Extended Control API 38 The Extended Control API
39 ======================== 39 ========================
40 40
41 Three new ioctls are available: 41 Three new ioctls are available:
42 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` 42 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
43 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` 43 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
44 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS 44 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. These ioctls act
45 on arrays of controls (as opposed to the 45 on arrays of controls (as opposed to the
46 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and 46 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
47 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls th 47 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls that act on a single
48 control). This is needed since it is often req 48 control). This is needed since it is often required to atomically change
49 several controls at once. 49 several controls at once.
50 50
51 Each of the new ioctls expects a pointer to a 51 Each of the new ioctls expects a pointer to a struct
52 :c:type:`v4l2_ext_controls`. This structure 52 :c:type:`v4l2_ext_controls`. This structure
53 contains a pointer to the control array, a cou 53 contains a pointer to the control array, a count of the number of
54 controls in that array and a control class. Co 54 controls in that array and a control class. Control classes are used to
55 group similar controls into a single class. Fo 55 group similar controls into a single class. For example, control class
56 ``V4L2_CTRL_CLASS_USER`` contains all user con 56 ``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls
57 that can also be set using the old :ref:`VIDIO 57 that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
58 ioctl). Control class ``V4L2_CTRL_CLASS_CODEC` 58 ioctl). Control class ``V4L2_CTRL_CLASS_CODEC`` contains controls
59 relating to codecs. 59 relating to codecs.
60 60
61 All controls in the control array must belong 61 All controls in the control array must belong to the specified control
62 class. An error is returned if this is not the 62 class. An error is returned if this is not the case.
63 63
64 It is also possible to use an empty control ar 64 It is also possible to use an empty control array (``count`` == 0) to check
65 whether the specified control class is support 65 whether the specified control class is supported.
66 66
67 The control array is a struct 67 The control array is a struct
68 :c:type:`v4l2_ext_control` array. The 68 :c:type:`v4l2_ext_control` array. The
69 struct :c:type:`v4l2_ext_control` is very simi 69 struct :c:type:`v4l2_ext_control` is very similar to
70 struct :c:type:`v4l2_control`, except for the 70 struct :c:type:`v4l2_control`, except for the fact that
71 it also allows for 64-bit values and pointers 71 it also allows for 64-bit values and pointers to be passed.
72 72
73 Since the struct :c:type:`v4l2_ext_control` su 73 Since the struct :c:type:`v4l2_ext_control` supports
74 pointers it is now also possible to have contr 74 pointers it is now also possible to have controls with compound types
75 such as N-dimensional arrays and/or structures 75 such as N-dimensional arrays and/or structures. You need to specify the
76 ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerat 76 ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerating controls to actually
77 be able to see such compound controls. In othe 77 be able to see such compound controls. In other words, these controls
78 with compound types should only be used progra 78 with compound types should only be used programmatically.
79 79
80 Since such compound controls need to expose mo 80 Since such compound controls need to expose more information about
81 themselves than is possible with :ref:`VIDIOC_ 81 themselves than is possible with :ref:`VIDIOC_QUERYCTRL <VIDIOC_QUERYCTRL>`
82 the :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYC 82 the :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In
83 particular, this ioctl gives the dimensions of 83 particular, this ioctl gives the dimensions of the N-dimensional array if
84 this control consists of more than one element 84 this control consists of more than one element.
85 85
86 .. note:: 86 .. note::
87 87
88 #. It is important to realize that due to t 88 #. It is important to realize that due to the flexibility of controls it is
89 necessary to check whether the control y 89 necessary to check whether the control you want to set actually is
90 supported in the driver and what the val 90 supported in the driver and what the valid range of values is. So use
91 :ref:`VIDIOC_QUERYCTRL` to check this. 91 :ref:`VIDIOC_QUERYCTRL` to check this.
92 92
93 #. It is possible that some of the menu ind 93 #. It is possible that some of the menu indices in a control of
94 type ``V4L2_CTRL_TYPE_MENU`` may not be 94 type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU``
95 will return an error). A good example is 95 will return an error). A good example is the list of supported MPEG
96 audio bitrates. Some drivers only suppor 96 audio bitrates. Some drivers only support one or two bitrates, others
97 support a wider range. 97 support a wider range.
98 98
99 All controls use machine endianness. 99 All controls use machine endianness.
100 100
101 101
102 Enumerating Extended Controls 102 Enumerating Extended Controls
103 ============================= 103 =============================
104 104
105 The recommended way to enumerate over the exte 105 The recommended way to enumerate over the extended controls is by using
106 :ref:`VIDIOC_QUERYCTRL` in combination with th 106 :ref:`VIDIOC_QUERYCTRL` in combination with the
107 ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag: 107 ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag:
108 108
109 109
110 .. code-block:: c 110 .. code-block:: c
111 111
112 struct v4l2_queryctrl qctrl; 112 struct v4l2_queryctrl qctrl;
113 113
114 qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL; 114 qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
115 while (0 == ioctl (fd, VIDIOC_QUERYCTRL, & 115 while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
116 /* ... */ 116 /* ... */
117 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; 117 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
118 } 118 }
119 119
120 The initial control ID is set to 0 ORed with t 120 The initial control ID is set to 0 ORed with the
121 ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIO 121 ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIOC_QUERYCTRL`` ioctl will
122 return the first control with a higher ID than 122 return the first control with a higher ID than the specified one. When
123 no such controls are found an error is returne 123 no such controls are found an error is returned.
124 124
125 If you want to get all controls within a speci 125 If you want to get all controls within a specific control class, then
126 you can set the initial ``qctrl.id`` value to 126 you can set the initial ``qctrl.id`` value to the control class and add
127 an extra check to break out of the loop when a 127 an extra check to break out of the loop when a control of another
128 control class is found: 128 control class is found:
129 129
130 130
131 .. code-block:: c 131 .. code-block:: c
132 132
133 qctrl.id = V4L2_CTRL_CLASS_CODEC | V4L2_CT 133 qctrl.id = V4L2_CTRL_CLASS_CODEC | V4L2_CTRL_FLAG_NEXT_CTRL;
134 while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &q 134 while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) {
135 if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4 135 if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_CODEC)
136 break; 136 break;
137 /* ... */ 137 /* ... */
138 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; 138 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
139 } 139 }
140 140
141 The 32-bit ``qctrl.id`` value is subdivided in 141 The 32-bit ``qctrl.id`` value is subdivided into three bit ranges: the
142 top 4 bits are reserved for flags (e. g. ``V4L 142 top 4 bits are reserved for flags (e. g. ``V4L2_CTRL_FLAG_NEXT_CTRL``)
143 and are not actually part of the ID. The remai 143 and are not actually part of the ID. The remaining 28 bits form the
144 control ID, of which the most significant 12 b 144 control ID, of which the most significant 12 bits define the control
145 class and the least significant 16 bits identi 145 class and the least significant 16 bits identify the control within the
146 control class. It is guaranteed that these las 146 control class. It is guaranteed that these last 16 bits are always
147 non-zero for controls. The range of 0x1000 and 147 non-zero for controls. The range of 0x1000 and up are reserved for
148 driver-specific controls. The macro ``V4L2_CTR 148 driver-specific controls. The macro ``V4L2_CTRL_ID2CLASS(id)`` returns
149 the control class ID based on a control ID. 149 the control class ID based on a control ID.
150 150
151 If the driver does not support extended contro 151 If the driver does not support extended controls, then
152 ``VIDIOC_QUERYCTRL`` will fail when used in co 152 ``VIDIOC_QUERYCTRL`` will fail when used in combination with
153 ``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the 153 ``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the old method of enumerating
154 control should be used (see :ref:`enum_all_con 154 control should be used (see :ref:`enum_all_controls`). But if it is
155 supported, then it is guaranteed to enumerate 155 supported, then it is guaranteed to enumerate over all controls,
156 including driver-private controls. 156 including driver-private controls.
157 157
158 158
159 Creating Control Panels 159 Creating Control Panels
160 ======================= 160 =======================
161 161
162 It is possible to create control panels for a 162 It is possible to create control panels for a graphical user interface
163 where the user can select the various controls 163 where the user can select the various controls. Basically you will have
164 to iterate over all controls using the method 164 to iterate over all controls using the method described above. Each
165 control class starts with a control of type 165 control class starts with a control of type
166 ``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYC 166 ``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYCTRL`` will return the name
167 of this control class which can be used as the 167 of this control class which can be used as the title of a tab page
168 within a control panel. 168 within a control panel.
169 169
170 The flags field of struct :ref:`v4l2_queryctrl 170 The flags field of struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` also
171 contains hints on the behavior of the control. 171 contains hints on the behavior of the control. See the
172 :ref:`VIDIOC_QUERYCTRL` documentation for more 172 :ref:`VIDIOC_QUERYCTRL` documentation for more
173 details. 173 details.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.