174 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2 3.. _extended-controls:4 5*********************6Extended Controls API7*********************8 9 10Introduction11============12 13The control mechanism as originally designed was meant to be used for14user settings (brightness, saturation, etc). However, it turned out to15be a very useful model for implementing more complicated driver APIs16where each driver implements only a subset of a larger API.17 18The MPEG encoding API was the driving force behind designing and19implementing this extended control mechanism: the MPEG standard is quite20large and the currently supported hardware MPEG encoders each only21implement a subset of this standard. Further more, many parameters22relating to how the video is encoded into an MPEG stream are specific to23the MPEG encoding chip since the MPEG standard only defines the format24of the resulting MPEG stream, not how the video is actually encoded into25that format.26 27Unfortunately, the original control API lacked some features needed for28these new uses and so it was extended into the (not terribly originally29named) extended control API.30 31Even though the MPEG encoding API was the first effort to use the32Extended Control API, nowadays there are also other classes of Extended33Controls, such as Camera Controls and FM Transmitter Controls. The34Extended Controls API as well as all Extended Controls classes are35described in the following text.36 37 38The Extended Control API39========================40 41Three new ioctls are available:42:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,43:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and44:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. These ioctls act45on arrays of controls (as opposed to the46:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and47:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls that act on a single48control). This is needed since it is often required to atomically change49several controls at once.50 51Each of the new ioctls expects a pointer to a struct52:c:type:`v4l2_ext_controls`. This structure53contains a pointer to the control array, a count of the number of54controls in that array and a control class. Control classes are used to55group similar controls into a single class. For example, control class56``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls57that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`58ioctl). Control class ``V4L2_CTRL_CLASS_CODEC`` contains controls59relating to codecs.60 61All controls in the control array must belong to the specified control62class. An error is returned if this is not the case.63 64It is also possible to use an empty control array (``count`` == 0) to check65whether the specified control class is supported.66 67The control array is a struct68:c:type:`v4l2_ext_control` array. The69struct :c:type:`v4l2_ext_control` is very similar to70struct :c:type:`v4l2_control`, except for the fact that71it also allows for 64-bit values and pointers to be passed.72 73Since the struct :c:type:`v4l2_ext_control` supports74pointers it is now also possible to have controls with compound types75such as N-dimensional arrays and/or structures. You need to specify the76``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerating controls to actually77be able to see such compound controls. In other words, these controls78with compound types should only be used programmatically.79 80Since such compound controls need to expose more information about81themselves than is possible with :ref:`VIDIOC_QUERYCTRL <VIDIOC_QUERYCTRL>`82the :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In83particular, this ioctl gives the dimensions of the N-dimensional array if84this control consists of more than one element.85 86.. note::87 88 #. It is important to realize that due to the flexibility of controls it is89 necessary to check whether the control you want to set actually is90 supported in the driver and what the valid range of values is. So use91 :ref:`VIDIOC_QUERYCTRL` to check this.92 93 #. It is possible that some of the menu indices in a control of94 type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU``95 will return an error). A good example is the list of supported MPEG96 audio bitrates. Some drivers only support one or two bitrates, others97 support a wider range.98 99All controls use machine endianness.100 101 102Enumerating Extended Controls103=============================104 105The recommended way to enumerate over the extended controls is by using106:ref:`VIDIOC_QUERYCTRL` in combination with the107``V4L2_CTRL_FLAG_NEXT_CTRL`` flag:108 109 110.. code-block:: c111 112 struct v4l2_queryctrl qctrl;113 114 qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;115 while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {116 /* ... */117 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;118 }119 120The initial control ID is set to 0 ORed with the121``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIOC_QUERYCTRL`` ioctl will122return the first control with a higher ID than the specified one. When123no such controls are found an error is returned.124 125If you want to get all controls within a specific control class, then126you can set the initial ``qctrl.id`` value to the control class and add127an extra check to break out of the loop when a control of another128control class is found:129 130 131.. code-block:: c132 133 qctrl.id = V4L2_CTRL_CLASS_CODEC | V4L2_CTRL_FLAG_NEXT_CTRL;134 while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) {135 if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_CODEC)136 break;137 /* ... */138 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;139 }140 141The 32-bit ``qctrl.id`` value is subdivided into three bit ranges: the142top 4 bits are reserved for flags (e. g. ``V4L2_CTRL_FLAG_NEXT_CTRL``)143and are not actually part of the ID. The remaining 28 bits form the144control ID, of which the most significant 12 bits define the control145class and the least significant 16 bits identify the control within the146control class. It is guaranteed that these last 16 bits are always147non-zero for controls. The range of 0x1000 and up are reserved for148driver-specific controls. The macro ``V4L2_CTRL_ID2CLASS(id)`` returns149the control class ID based on a control ID.150 151If the driver does not support extended controls, then152``VIDIOC_QUERYCTRL`` will fail when used in combination with153``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the old method of enumerating154control should be used (see :ref:`enum_all_controls`). But if it is155supported, then it is guaranteed to enumerate over all controls,156including driver-private controls.157 158 159Creating Control Panels160=======================161 162It is possible to create control panels for a graphical user interface163where the user can select the various controls. Basically you will have164to iterate over all controls using the method described above. Each165control class starts with a control of type166``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYCTRL`` will return the name167of this control class which can be used as the title of a tab page168within a control panel.169 170The flags field of struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` also171contains hints on the behavior of the control. See the172:ref:`VIDIOC_QUERYCTRL` documentation for more173details.174