Documentation/userspace-api/media/v4l/extended-controls.rst

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