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