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