extended-controls.rst

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