media/v4l/extended-controls.rst

1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
3 .. _extended-controls:
13 The control mechanism as originally designed was meant to be used for
19 implementing this extended control mechanism: the MPEG standard is quite
27 Unfortunately, the original control API lacked some features needed for
29 named) extended control API.
32 Extended Control API, nowadays there are also other classes of Extended
38 The Extended Control API
48 control). This is needed since it is often required to atomically change
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
58 ioctl). Control class ``V4L2_CTRL_CLASS_CODEC`` contains controls
61 All controls in the control array must belong to the specified control
64 It is also possible to use an empty control array (``count`` == 0) to check
65 whether the specified control class is supported.
67 The control array is a struct
71 it also allows for 64-bit values and pointers to be passed.
75 such as N-dimensional arrays and/or structures. You need to specify the
83 particular, this ioctl gives the dimensions of the N-dimensional array if
84 this control consists of more than one element.
89       necessary to check whether the control you want to set actually is
93    #. It is possible that some of the menu indices in a control of
110 .. code-block:: c
120 The initial control ID is set to 0 ORed with the
122 return the first control with a higher ID than the specified one. When
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:
131 .. code-block:: c
141 The 32-bit ``qctrl.id`` value is subdivided into three bit ranges: 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.
154 control should be used (see :ref:`enum_all_controls`). But if it is
156 including driver-private controls.
159 Creating Control Panels
162 It is possible to create control panels for a graphical user interface
165 control class starts with a control of type
167 of this control class which can be used as the title of a tab page
168 within a control panel.
170 The flags field of struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` also
171 contains hints on the behavior of the control. See the