1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 254f38fcaSMauro Carvalho Chehab 354f38fcaSMauro Carvalho Chehab.. _extended-controls: 454f38fcaSMauro Carvalho Chehab 554f38fcaSMauro Carvalho Chehab********************* 654f38fcaSMauro Carvalho ChehabExtended Controls API 754f38fcaSMauro Carvalho Chehab********************* 854f38fcaSMauro Carvalho Chehab 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabIntroduction 1154f38fcaSMauro Carvalho Chehab============ 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabThe control mechanism as originally designed was meant to be used for 1454f38fcaSMauro Carvalho Chehabuser settings (brightness, saturation, etc). However, it turned out to 1554f38fcaSMauro Carvalho Chehabbe a very useful model for implementing more complicated driver APIs 1654f38fcaSMauro Carvalho Chehabwhere each driver implements only a subset of a larger API. 1754f38fcaSMauro Carvalho Chehab 1854f38fcaSMauro Carvalho ChehabThe MPEG encoding API was the driving force behind designing and 1954f38fcaSMauro Carvalho Chehabimplementing this extended control mechanism: the MPEG standard is quite 2054f38fcaSMauro Carvalho Chehablarge and the currently supported hardware MPEG encoders each only 2154f38fcaSMauro Carvalho Chehabimplement a subset of this standard. Further more, many parameters 2254f38fcaSMauro Carvalho Chehabrelating to how the video is encoded into an MPEG stream are specific to 2354f38fcaSMauro Carvalho Chehabthe MPEG encoding chip since the MPEG standard only defines the format 2454f38fcaSMauro Carvalho Chehabof the resulting MPEG stream, not how the video is actually encoded into 2554f38fcaSMauro Carvalho Chehabthat format. 2654f38fcaSMauro Carvalho Chehab 2754f38fcaSMauro Carvalho ChehabUnfortunately, the original control API lacked some features needed for 2854f38fcaSMauro Carvalho Chehabthese new uses and so it was extended into the (not terribly originally 2954f38fcaSMauro Carvalho Chehabnamed) extended control API. 3054f38fcaSMauro Carvalho Chehab 3154f38fcaSMauro Carvalho ChehabEven though the MPEG encoding API was the first effort to use the 3254f38fcaSMauro Carvalho ChehabExtended Control API, nowadays there are also other classes of Extended 3354f38fcaSMauro Carvalho ChehabControls, such as Camera Controls and FM Transmitter Controls. The 3454f38fcaSMauro Carvalho ChehabExtended Controls API as well as all Extended Controls classes are 3554f38fcaSMauro Carvalho Chehabdescribed in the following text. 3654f38fcaSMauro Carvalho Chehab 3754f38fcaSMauro Carvalho Chehab 3854f38fcaSMauro Carvalho ChehabThe Extended Control API 3954f38fcaSMauro Carvalho Chehab======================== 4054f38fcaSMauro Carvalho Chehab 4154f38fcaSMauro Carvalho ChehabThree new ioctls are available: 4254f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, 4354f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and 4454f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. These ioctls act 4554f38fcaSMauro Carvalho Chehabon arrays of controls (as opposed to the 4654f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and 4754f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls that act on a single 4854f38fcaSMauro Carvalho Chehabcontrol). This is needed since it is often required to atomically change 4954f38fcaSMauro Carvalho Chehabseveral controls at once. 5054f38fcaSMauro Carvalho Chehab 5154f38fcaSMauro Carvalho ChehabEach of the new ioctls expects a pointer to a struct 5254f38fcaSMauro Carvalho Chehab:c:type:`v4l2_ext_controls`. This structure 5354f38fcaSMauro Carvalho Chehabcontains a pointer to the control array, a count of the number of 5454f38fcaSMauro Carvalho Chehabcontrols in that array and a control class. Control classes are used to 5554f38fcaSMauro Carvalho Chehabgroup similar controls into a single class. For example, control class 5654f38fcaSMauro Carvalho Chehab``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls 5754f38fcaSMauro Carvalho Chehabthat can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` 58*35aaa6e6SEzequiel Garciaioctl). Control class ``V4L2_CTRL_CLASS_CODEC`` contains controls 59*35aaa6e6SEzequiel Garciarelating to codecs. 6054f38fcaSMauro Carvalho Chehab 6154f38fcaSMauro Carvalho ChehabAll controls in the control array must belong to the specified control 6254f38fcaSMauro Carvalho Chehabclass. An error is returned if this is not the case. 6354f38fcaSMauro Carvalho Chehab 6454f38fcaSMauro Carvalho ChehabIt is also possible to use an empty control array (``count`` == 0) to check 6554f38fcaSMauro Carvalho Chehabwhether the specified control class is supported. 6654f38fcaSMauro Carvalho Chehab 6754f38fcaSMauro Carvalho ChehabThe control array is a struct 6854f38fcaSMauro Carvalho Chehab:c:type:`v4l2_ext_control` array. The 6954f38fcaSMauro Carvalho Chehabstruct :c:type:`v4l2_ext_control` is very similar to 7054f38fcaSMauro Carvalho Chehabstruct :c:type:`v4l2_control`, except for the fact that 7154f38fcaSMauro Carvalho Chehabit also allows for 64-bit values and pointers to be passed. 7254f38fcaSMauro Carvalho Chehab 7354f38fcaSMauro Carvalho ChehabSince the struct :c:type:`v4l2_ext_control` supports 7454f38fcaSMauro Carvalho Chehabpointers it is now also possible to have controls with compound types 7554f38fcaSMauro Carvalho Chehabsuch as N-dimensional arrays and/or structures. You need to specify the 7654f38fcaSMauro Carvalho Chehab``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerating controls to actually 7754f38fcaSMauro Carvalho Chehabbe able to see such compound controls. In other words, these controls 7854f38fcaSMauro Carvalho Chehabwith compound types should only be used programmatically. 7954f38fcaSMauro Carvalho Chehab 8054f38fcaSMauro Carvalho ChehabSince such compound controls need to expose more information about 8154f38fcaSMauro Carvalho Chehabthemselves than is possible with :ref:`VIDIOC_QUERYCTRL <VIDIOC_QUERYCTRL>` 8254f38fcaSMauro Carvalho Chehabthe :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In 8354f38fcaSMauro Carvalho Chehabparticular, this ioctl gives the dimensions of the N-dimensional array if 8454f38fcaSMauro Carvalho Chehabthis control consists of more than one element. 8554f38fcaSMauro Carvalho Chehab 8654f38fcaSMauro Carvalho Chehab.. note:: 8754f38fcaSMauro Carvalho Chehab 8854f38fcaSMauro Carvalho Chehab #. It is important to realize that due to the flexibility of controls it is 8954f38fcaSMauro Carvalho Chehab necessary to check whether the control you want to set actually is 9054f38fcaSMauro Carvalho Chehab supported in the driver and what the valid range of values is. So use 9154f38fcaSMauro Carvalho Chehab :ref:`VIDIOC_QUERYCTRL` to check this. 9254f38fcaSMauro Carvalho Chehab 9354f38fcaSMauro Carvalho Chehab #. It is possible that some of the menu indices in a control of 9454f38fcaSMauro Carvalho Chehab type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU`` 9554f38fcaSMauro Carvalho Chehab will return an error). A good example is the list of supported MPEG 9654f38fcaSMauro Carvalho Chehab audio bitrates. Some drivers only support one or two bitrates, others 9754f38fcaSMauro Carvalho Chehab support a wider range. 9854f38fcaSMauro Carvalho Chehab 9954f38fcaSMauro Carvalho ChehabAll controls use machine endianness. 10054f38fcaSMauro Carvalho Chehab 10154f38fcaSMauro Carvalho Chehab 10254f38fcaSMauro Carvalho ChehabEnumerating Extended Controls 10354f38fcaSMauro Carvalho Chehab============================= 10454f38fcaSMauro Carvalho Chehab 10554f38fcaSMauro Carvalho ChehabThe recommended way to enumerate over the extended controls is by using 10654f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_QUERYCTRL` in combination with the 10754f38fcaSMauro Carvalho Chehab``V4L2_CTRL_FLAG_NEXT_CTRL`` flag: 10854f38fcaSMauro Carvalho Chehab 10954f38fcaSMauro Carvalho Chehab 11054f38fcaSMauro Carvalho Chehab.. code-block:: c 11154f38fcaSMauro Carvalho Chehab 11254f38fcaSMauro Carvalho Chehab struct v4l2_queryctrl qctrl; 11354f38fcaSMauro Carvalho Chehab 11454f38fcaSMauro Carvalho Chehab qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL; 11554f38fcaSMauro Carvalho Chehab while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) { 11654f38fcaSMauro Carvalho Chehab /* ... */ 11754f38fcaSMauro Carvalho Chehab qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; 11854f38fcaSMauro Carvalho Chehab } 11954f38fcaSMauro Carvalho Chehab 12054f38fcaSMauro Carvalho ChehabThe initial control ID is set to 0 ORed with the 12154f38fcaSMauro Carvalho Chehab``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIOC_QUERYCTRL`` ioctl will 12254f38fcaSMauro Carvalho Chehabreturn the first control with a higher ID than the specified one. When 12354f38fcaSMauro Carvalho Chehabno such controls are found an error is returned. 12454f38fcaSMauro Carvalho Chehab 12554f38fcaSMauro Carvalho ChehabIf you want to get all controls within a specific control class, then 12654f38fcaSMauro Carvalho Chehabyou can set the initial ``qctrl.id`` value to the control class and add 12754f38fcaSMauro Carvalho Chehaban extra check to break out of the loop when a control of another 12854f38fcaSMauro Carvalho Chehabcontrol class is found: 12954f38fcaSMauro Carvalho Chehab 13054f38fcaSMauro Carvalho Chehab 13154f38fcaSMauro Carvalho Chehab.. code-block:: c 13254f38fcaSMauro Carvalho Chehab 133*35aaa6e6SEzequiel Garcia qctrl.id = V4L2_CTRL_CLASS_CODEC | V4L2_CTRL_FLAG_NEXT_CTRL; 13454f38fcaSMauro Carvalho Chehab while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) { 135*35aaa6e6SEzequiel Garcia if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_CODEC) 13654f38fcaSMauro Carvalho Chehab break; 13754f38fcaSMauro Carvalho Chehab /* ... */ 13854f38fcaSMauro Carvalho Chehab qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; 13954f38fcaSMauro Carvalho Chehab } 14054f38fcaSMauro Carvalho Chehab 14154f38fcaSMauro Carvalho ChehabThe 32-bit ``qctrl.id`` value is subdivided into three bit ranges: the 14254f38fcaSMauro Carvalho Chehabtop 4 bits are reserved for flags (e. g. ``V4L2_CTRL_FLAG_NEXT_CTRL``) 14354f38fcaSMauro Carvalho Chehaband are not actually part of the ID. The remaining 28 bits form the 14454f38fcaSMauro Carvalho Chehabcontrol ID, of which the most significant 12 bits define the control 14554f38fcaSMauro Carvalho Chehabclass and the least significant 16 bits identify the control within the 14654f38fcaSMauro Carvalho Chehabcontrol class. It is guaranteed that these last 16 bits are always 14754f38fcaSMauro Carvalho Chehabnon-zero for controls. The range of 0x1000 and up are reserved for 14854f38fcaSMauro Carvalho Chehabdriver-specific controls. The macro ``V4L2_CTRL_ID2CLASS(id)`` returns 14954f38fcaSMauro Carvalho Chehabthe control class ID based on a control ID. 15054f38fcaSMauro Carvalho Chehab 15154f38fcaSMauro Carvalho ChehabIf the driver does not support extended controls, then 15254f38fcaSMauro Carvalho Chehab``VIDIOC_QUERYCTRL`` will fail when used in combination with 15354f38fcaSMauro Carvalho Chehab``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the old method of enumerating 15454f38fcaSMauro Carvalho Chehabcontrol should be used (see :ref:`enum_all_controls`). But if it is 15554f38fcaSMauro Carvalho Chehabsupported, then it is guaranteed to enumerate over all controls, 15654f38fcaSMauro Carvalho Chehabincluding driver-private controls. 15754f38fcaSMauro Carvalho Chehab 15854f38fcaSMauro Carvalho Chehab 15954f38fcaSMauro Carvalho ChehabCreating Control Panels 16054f38fcaSMauro Carvalho Chehab======================= 16154f38fcaSMauro Carvalho Chehab 16254f38fcaSMauro Carvalho ChehabIt is possible to create control panels for a graphical user interface 16354f38fcaSMauro Carvalho Chehabwhere the user can select the various controls. Basically you will have 16454f38fcaSMauro Carvalho Chehabto iterate over all controls using the method described above. Each 16554f38fcaSMauro Carvalho Chehabcontrol class starts with a control of type 16654f38fcaSMauro Carvalho Chehab``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYCTRL`` will return the name 16754f38fcaSMauro Carvalho Chehabof this control class which can be used as the title of a tab page 16854f38fcaSMauro Carvalho Chehabwithin a control panel. 16954f38fcaSMauro Carvalho Chehab 17054f38fcaSMauro Carvalho ChehabThe flags field of struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` also 17154f38fcaSMauro Carvalho Chehabcontains hints on the behavior of the control. See the 17254f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_QUERYCTRL` documentation for more 17354f38fcaSMauro Carvalho Chehabdetails. 174