Documentation/media/uapi/v4l/extended-controls.rst

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