1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _VIDIOC_QUERYCTRL: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab******************************************************************* 754f38fcaSMauro Carvalho Chehabioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU 854f38fcaSMauro Carvalho Chehab******************************************************************* 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabName 1154f38fcaSMauro Carvalho Chehab==== 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabVIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabSynopsis 1654f38fcaSMauro Carvalho Chehab======== 1754f38fcaSMauro Carvalho Chehab 18407e84cdSMauro Carvalho Chehab``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)`` 1954f38fcaSMauro Carvalho Chehab 20407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_QUERY_EXT_CTRL 2154f38fcaSMauro Carvalho Chehab 22407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)`` 2354f38fcaSMauro Carvalho Chehab 24407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_QUERYMENU 25407e84cdSMauro Carvalho Chehab 26407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)`` 2754f38fcaSMauro Carvalho Chehab 2854f38fcaSMauro Carvalho ChehabArguments 2954f38fcaSMauro Carvalho Chehab========= 3054f38fcaSMauro Carvalho Chehab 3154f38fcaSMauro Carvalho Chehab``fd`` 32407e84cdSMauro Carvalho Chehab File descriptor returned by :c:func:`open()`. 3354f38fcaSMauro Carvalho Chehab 3454f38fcaSMauro Carvalho Chehab``argp`` 3554f38fcaSMauro Carvalho Chehab Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl` 3654f38fcaSMauro Carvalho Chehab or :c:type:`v4l2_querymenu` (depending on the ioctl). 3754f38fcaSMauro Carvalho Chehab 3854f38fcaSMauro Carvalho ChehabDescription 3954f38fcaSMauro Carvalho Chehab=========== 4054f38fcaSMauro Carvalho Chehab 4154f38fcaSMauro Carvalho ChehabTo query the attributes of a control applications set the ``id`` field 4254f38fcaSMauro Carvalho Chehabof a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the 4354f38fcaSMauro Carvalho Chehab``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver 4454f38fcaSMauro Carvalho Chehabfills the rest of the structure or returns an ``EINVAL`` error code when the 4554f38fcaSMauro Carvalho Chehab``id`` is invalid. 4654f38fcaSMauro Carvalho Chehab 4754f38fcaSMauro Carvalho ChehabIt is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL`` 4854f38fcaSMauro Carvalho Chehabwith successive ``id`` values starting from ``V4L2_CID_BASE`` up to and 4954f38fcaSMauro Carvalho Chehabexclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in 5054f38fcaSMauro Carvalho Chehabthis range is not supported. Further applications can enumerate private 5154f38fcaSMauro Carvalho Chehabcontrols, which are not defined in this specification, by starting at 5254f38fcaSMauro Carvalho Chehab``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver 5354f38fcaSMauro Carvalho Chehabreturns ``EINVAL``. 5454f38fcaSMauro Carvalho Chehab 5554f38fcaSMauro Carvalho ChehabIn both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag 5654f38fcaSMauro Carvalho Chehabin the ``flags`` field this control is permanently disabled and should 5754f38fcaSMauro Carvalho Chehabbe ignored by the application. [#f1]_ 5854f38fcaSMauro Carvalho Chehab 5954f38fcaSMauro Carvalho ChehabWhen the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the 6054f38fcaSMauro Carvalho Chehabdriver returns the next supported non-compound control, or ``EINVAL`` if 6154f38fcaSMauro Carvalho Chehabthere is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag 6254f38fcaSMauro Carvalho Chehabcan be specified to enumerate all compound controls (i.e. controls with 6354f38fcaSMauro Carvalho Chehabtype ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words 6454f38fcaSMauro Carvalho Chehabcontrols that contain more than one value). Specify both 6554f38fcaSMauro Carvalho Chehab``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in 6654f38fcaSMauro Carvalho Chehaborder to enumerate all controls, compound or not. Drivers which do not 6754f38fcaSMauro Carvalho Chehabsupport these flags yet always return ``EINVAL``. 6854f38fcaSMauro Carvalho Chehab 6954f38fcaSMauro Carvalho ChehabThe ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better 7054f38fcaSMauro Carvalho Chehabsupport controls that can use compound types, and to expose additional 7154f38fcaSMauro Carvalho Chehabcontrol information that cannot be returned in struct 7254f38fcaSMauro Carvalho Chehab:ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full. 7354f38fcaSMauro Carvalho Chehab 7454f38fcaSMauro Carvalho Chehab``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as 7554f38fcaSMauro Carvalho Chehab``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed 7654f38fcaSMauro Carvalho Chehabas well. 7754f38fcaSMauro Carvalho Chehab 7854f38fcaSMauro Carvalho ChehabAdditional information is required for menu controls: the names of the 7954f38fcaSMauro Carvalho Chehabmenu items. To query them applications set the ``id`` and ``index`` 8054f38fcaSMauro Carvalho Chehabfields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the 8154f38fcaSMauro Carvalho Chehab``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver 8254f38fcaSMauro Carvalho Chehabfills the rest of the structure or returns an ``EINVAL`` error code when the 8354f38fcaSMauro Carvalho Chehab``id`` or ``index`` is invalid. Menu items are enumerated by calling 8454f38fcaSMauro Carvalho Chehab``VIDIOC_QUERYMENU`` with successive ``index`` values from struct 8554f38fcaSMauro Carvalho Chehab:ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``, 8654f38fcaSMauro Carvalho Chehabinclusive. 8754f38fcaSMauro Carvalho Chehab 8854f38fcaSMauro Carvalho Chehab.. note:: 8954f38fcaSMauro Carvalho Chehab 9054f38fcaSMauro Carvalho Chehab It is possible for ``VIDIOC_QUERYMENU`` to return 9154f38fcaSMauro Carvalho Chehab an ``EINVAL`` error code for some indices between ``minimum`` and 9254f38fcaSMauro Carvalho Chehab ``maximum``. In that case that particular menu item is not supported by 9354f38fcaSMauro Carvalho Chehab this driver. Also note that the ``minimum`` value is not necessarily 0. 9454f38fcaSMauro Carvalho Chehab 9554f38fcaSMauro Carvalho ChehabSee also the examples in :ref:`control`. 9654f38fcaSMauro Carvalho Chehab 97fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.5cm}| 9854f38fcaSMauro Carvalho Chehab 9954f38fcaSMauro Carvalho Chehab.. _v4l2-queryctrl: 10054f38fcaSMauro Carvalho Chehab 10154f38fcaSMauro Carvalho Chehab.. cssclass:: longtable 10254f38fcaSMauro Carvalho Chehab 10354f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_queryctrl 10454f38fcaSMauro Carvalho Chehab :header-rows: 0 10554f38fcaSMauro Carvalho Chehab :stub-columns: 0 10654f38fcaSMauro Carvalho Chehab :widths: 1 1 2 10754f38fcaSMauro Carvalho Chehab 10854f38fcaSMauro Carvalho Chehab * - __u32 10954f38fcaSMauro Carvalho Chehab - ``id`` 11054f38fcaSMauro Carvalho Chehab - Identifies the control, set by the application. See 11154f38fcaSMauro Carvalho Chehab :ref:`control-id` for predefined IDs. When the ID is ORed with 11254f38fcaSMauro Carvalho Chehab V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and 11354f38fcaSMauro Carvalho Chehab returns the first control with a higher ID. Drivers which do not 11454f38fcaSMauro Carvalho Chehab support this flag yet always return an ``EINVAL`` error code. 11554f38fcaSMauro Carvalho Chehab * - __u32 11654f38fcaSMauro Carvalho Chehab - ``type`` 11754f38fcaSMauro Carvalho Chehab - Type of control, see :c:type:`v4l2_ctrl_type`. 11854f38fcaSMauro Carvalho Chehab * - __u8 11954f38fcaSMauro Carvalho Chehab - ``name``\ [32] 12054f38fcaSMauro Carvalho Chehab - Name of the control, a NUL-terminated ASCII string. This 12154f38fcaSMauro Carvalho Chehab information is intended for the user. 12254f38fcaSMauro Carvalho Chehab * - __s32 12354f38fcaSMauro Carvalho Chehab - ``minimum`` 12454f38fcaSMauro Carvalho Chehab - Minimum value, inclusive. This field gives a lower bound for the 12554f38fcaSMauro Carvalho Chehab control. See enum :c:type:`v4l2_ctrl_type` how 12654f38fcaSMauro Carvalho Chehab the minimum value is to be used for each possible control type. 12754f38fcaSMauro Carvalho Chehab Note that this a signed 32-bit value. 12854f38fcaSMauro Carvalho Chehab * - __s32 12954f38fcaSMauro Carvalho Chehab - ``maximum`` 13054f38fcaSMauro Carvalho Chehab - Maximum value, inclusive. This field gives an upper bound for the 13154f38fcaSMauro Carvalho Chehab control. See enum :c:type:`v4l2_ctrl_type` how 13254f38fcaSMauro Carvalho Chehab the maximum value is to be used for each possible control type. 13354f38fcaSMauro Carvalho Chehab Note that this a signed 32-bit value. 13454f38fcaSMauro Carvalho Chehab * - __s32 13554f38fcaSMauro Carvalho Chehab - ``step`` 13654f38fcaSMauro Carvalho Chehab - This field gives a step size for the control. See enum 13754f38fcaSMauro Carvalho Chehab :c:type:`v4l2_ctrl_type` how the step value is 13854f38fcaSMauro Carvalho Chehab to be used for each possible control type. Note that this an 13954f38fcaSMauro Carvalho Chehab unsigned 32-bit value. 14054f38fcaSMauro Carvalho Chehab 14154f38fcaSMauro Carvalho Chehab Generally drivers should not scale hardware control values. It may 14254f38fcaSMauro Carvalho Chehab be necessary for example when the ``name`` or ``id`` imply a 14354f38fcaSMauro Carvalho Chehab particular unit and the hardware actually accepts only multiples 14454f38fcaSMauro Carvalho Chehab of said unit. If so, drivers must take care values are properly 14554f38fcaSMauro Carvalho Chehab rounded when scaling, such that errors will not accumulate on 14654f38fcaSMauro Carvalho Chehab repeated read-write cycles. 14754f38fcaSMauro Carvalho Chehab 14854f38fcaSMauro Carvalho Chehab This field gives the smallest change of an integer control 14954f38fcaSMauro Carvalho Chehab actually affecting hardware. Often the information is needed when 15054f38fcaSMauro Carvalho Chehab the user can change controls by keyboard or GUI buttons, rather 15154f38fcaSMauro Carvalho Chehab than a slider. When for example a hardware register accepts values 15254f38fcaSMauro Carvalho Chehab 0-511 and the driver reports 0-65535, step should be 128. 15354f38fcaSMauro Carvalho Chehab 15454f38fcaSMauro Carvalho Chehab Note that although signed, the step value is supposed to be always 15554f38fcaSMauro Carvalho Chehab positive. 15654f38fcaSMauro Carvalho Chehab * - __s32 15754f38fcaSMauro Carvalho Chehab - ``default_value`` 15854f38fcaSMauro Carvalho Chehab - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``, 15954f38fcaSMauro Carvalho Chehab ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid 16054f38fcaSMauro Carvalho Chehab for other types of controls. 16154f38fcaSMauro Carvalho Chehab 16254f38fcaSMauro Carvalho Chehab .. note:: 16354f38fcaSMauro Carvalho Chehab 16454f38fcaSMauro Carvalho Chehab Drivers reset controls to their default value only when 16554f38fcaSMauro Carvalho Chehab the driver is first loaded, never afterwards. 16654f38fcaSMauro Carvalho Chehab * - __u32 16754f38fcaSMauro Carvalho Chehab - ``flags`` 16854f38fcaSMauro Carvalho Chehab - Control flags, see :ref:`control-flags`. 16954f38fcaSMauro Carvalho Chehab * - __u32 17054f38fcaSMauro Carvalho Chehab - ``reserved``\ [2] 17154f38fcaSMauro Carvalho Chehab - Reserved for future extensions. Drivers must set the array to 17254f38fcaSMauro Carvalho Chehab zero. 17354f38fcaSMauro Carvalho Chehab 17454f38fcaSMauro Carvalho Chehab 175fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{1.2cm}|p{5.5cm}|p{10.6cm}| 17654f38fcaSMauro Carvalho Chehab 17754f38fcaSMauro Carvalho Chehab.. _v4l2-query-ext-ctrl: 17854f38fcaSMauro Carvalho Chehab 17954f38fcaSMauro Carvalho Chehab.. cssclass:: longtable 18054f38fcaSMauro Carvalho Chehab 18154f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_query_ext_ctrl 18254f38fcaSMauro Carvalho Chehab :header-rows: 0 18354f38fcaSMauro Carvalho Chehab :stub-columns: 0 18454f38fcaSMauro Carvalho Chehab :widths: 1 1 2 18554f38fcaSMauro Carvalho Chehab 18654f38fcaSMauro Carvalho Chehab * - __u32 18754f38fcaSMauro Carvalho Chehab - ``id`` 18854f38fcaSMauro Carvalho Chehab - Identifies the control, set by the application. See 18954f38fcaSMauro Carvalho Chehab :ref:`control-id` for predefined IDs. When the ID is ORed with 19054f38fcaSMauro Carvalho Chehab ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and 19154f38fcaSMauro Carvalho Chehab returns the first non-compound control with a higher ID. When the 19254f38fcaSMauro Carvalho Chehab ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears 19354f38fcaSMauro Carvalho Chehab the flag and returns the first compound control with a higher ID. 19454f38fcaSMauro Carvalho Chehab Set both to get the first control (compound or not) with a higher 19554f38fcaSMauro Carvalho Chehab ID. 19654f38fcaSMauro Carvalho Chehab * - __u32 19754f38fcaSMauro Carvalho Chehab - ``type`` 19854f38fcaSMauro Carvalho Chehab - Type of control, see :c:type:`v4l2_ctrl_type`. 19954f38fcaSMauro Carvalho Chehab * - char 20054f38fcaSMauro Carvalho Chehab - ``name``\ [32] 20154f38fcaSMauro Carvalho Chehab - Name of the control, a NUL-terminated ASCII string. This 20254f38fcaSMauro Carvalho Chehab information is intended for the user. 20354f38fcaSMauro Carvalho Chehab * - __s64 20454f38fcaSMauro Carvalho Chehab - ``minimum`` 20554f38fcaSMauro Carvalho Chehab - Minimum value, inclusive. This field gives a lower bound for the 20654f38fcaSMauro Carvalho Chehab control. See enum :c:type:`v4l2_ctrl_type` how 20754f38fcaSMauro Carvalho Chehab the minimum value is to be used for each possible control type. 20854f38fcaSMauro Carvalho Chehab Note that this a signed 64-bit value. 20954f38fcaSMauro Carvalho Chehab * - __s64 21054f38fcaSMauro Carvalho Chehab - ``maximum`` 21154f38fcaSMauro Carvalho Chehab - Maximum value, inclusive. This field gives an upper bound for the 21254f38fcaSMauro Carvalho Chehab control. See enum :c:type:`v4l2_ctrl_type` how 21354f38fcaSMauro Carvalho Chehab the maximum value is to be used for each possible control type. 21454f38fcaSMauro Carvalho Chehab Note that this a signed 64-bit value. 21554f38fcaSMauro Carvalho Chehab * - __u64 21654f38fcaSMauro Carvalho Chehab - ``step`` 21754f38fcaSMauro Carvalho Chehab - This field gives a step size for the control. See enum 21854f38fcaSMauro Carvalho Chehab :c:type:`v4l2_ctrl_type` how the step value is 21954f38fcaSMauro Carvalho Chehab to be used for each possible control type. Note that this an 22054f38fcaSMauro Carvalho Chehab unsigned 64-bit value. 22154f38fcaSMauro Carvalho Chehab 22254f38fcaSMauro Carvalho Chehab Generally drivers should not scale hardware control values. It may 22354f38fcaSMauro Carvalho Chehab be necessary for example when the ``name`` or ``id`` imply a 22454f38fcaSMauro Carvalho Chehab particular unit and the hardware actually accepts only multiples 22554f38fcaSMauro Carvalho Chehab of said unit. If so, drivers must take care values are properly 22654f38fcaSMauro Carvalho Chehab rounded when scaling, such that errors will not accumulate on 22754f38fcaSMauro Carvalho Chehab repeated read-write cycles. 22854f38fcaSMauro Carvalho Chehab 22954f38fcaSMauro Carvalho Chehab This field gives the smallest change of an integer control 23054f38fcaSMauro Carvalho Chehab actually affecting hardware. Often the information is needed when 23154f38fcaSMauro Carvalho Chehab the user can change controls by keyboard or GUI buttons, rather 23254f38fcaSMauro Carvalho Chehab than a slider. When for example a hardware register accepts values 23354f38fcaSMauro Carvalho Chehab 0-511 and the driver reports 0-65535, step should be 128. 23454f38fcaSMauro Carvalho Chehab * - __s64 23554f38fcaSMauro Carvalho Chehab - ``default_value`` 23654f38fcaSMauro Carvalho Chehab - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``, 23754f38fcaSMauro Carvalho Chehab ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8`` 23854f38fcaSMauro Carvalho Chehab or ``_U16`` control. Not valid for other types of controls. 23954f38fcaSMauro Carvalho Chehab 24054f38fcaSMauro Carvalho Chehab .. note:: 24154f38fcaSMauro Carvalho Chehab 24254f38fcaSMauro Carvalho Chehab Drivers reset controls to their default value only when 24354f38fcaSMauro Carvalho Chehab the driver is first loaded, never afterwards. 24454f38fcaSMauro Carvalho Chehab * - __u32 24554f38fcaSMauro Carvalho Chehab - ``flags`` 24654f38fcaSMauro Carvalho Chehab - Control flags, see :ref:`control-flags`. 24754f38fcaSMauro Carvalho Chehab * - __u32 24854f38fcaSMauro Carvalho Chehab - ``elem_size`` 24954f38fcaSMauro Carvalho Chehab - The size in bytes of a single element of the array. Given a char 25054f38fcaSMauro Carvalho Chehab pointer ``p`` to a 3-dimensional array you can find the position 25154f38fcaSMauro Carvalho Chehab of cell ``(z, y, x)`` as follows: 25254f38fcaSMauro Carvalho Chehab ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``. 25354f38fcaSMauro Carvalho Chehab ``elem_size`` is always valid, also when the control isn't an 25454f38fcaSMauro Carvalho Chehab array. For string controls ``elem_size`` is equal to 25554f38fcaSMauro Carvalho Chehab ``maximum + 1``. 25654f38fcaSMauro Carvalho Chehab * - __u32 25754f38fcaSMauro Carvalho Chehab - ``elems`` 25854f38fcaSMauro Carvalho Chehab - The number of elements in the N-dimensional array. If this control 25954f38fcaSMauro Carvalho Chehab is not an array, then ``elems`` is 1. The ``elems`` field can 26054f38fcaSMauro Carvalho Chehab never be 0. 26154f38fcaSMauro Carvalho Chehab * - __u32 26254f38fcaSMauro Carvalho Chehab - ``nr_of_dims`` 26354f38fcaSMauro Carvalho Chehab - The number of dimension in the N-dimensional array. If this 26454f38fcaSMauro Carvalho Chehab control is not an array, then this field is 0. 26554f38fcaSMauro Carvalho Chehab * - __u32 26654f38fcaSMauro Carvalho Chehab - ``dims[V4L2_CTRL_MAX_DIMS]`` 26754f38fcaSMauro Carvalho Chehab - The size of each dimension. The first ``nr_of_dims`` elements of 26854f38fcaSMauro Carvalho Chehab this array must be non-zero, all remaining elements must be zero. 26954f38fcaSMauro Carvalho Chehab * - __u32 27054f38fcaSMauro Carvalho Chehab - ``reserved``\ [32] 27154f38fcaSMauro Carvalho Chehab - Reserved for future extensions. Applications and drivers must set 27254f38fcaSMauro Carvalho Chehab the array to zero. 27354f38fcaSMauro Carvalho Chehab 27454f38fcaSMauro Carvalho Chehab 275fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}| 27654f38fcaSMauro Carvalho Chehab 27754f38fcaSMauro Carvalho Chehab.. _v4l2-querymenu: 27854f38fcaSMauro Carvalho Chehab 27954f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_querymenu 28054f38fcaSMauro Carvalho Chehab :header-rows: 0 28154f38fcaSMauro Carvalho Chehab :stub-columns: 0 28254f38fcaSMauro Carvalho Chehab :widths: 1 1 2 28354f38fcaSMauro Carvalho Chehab 28454f38fcaSMauro Carvalho Chehab * - __u32 28554f38fcaSMauro Carvalho Chehab - ``id`` 28654f38fcaSMauro Carvalho Chehab - Identifies the control, set by the application from the respective 28754f38fcaSMauro Carvalho Chehab struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``. 28854f38fcaSMauro Carvalho Chehab * - __u32 28954f38fcaSMauro Carvalho Chehab - ``index`` 29054f38fcaSMauro Carvalho Chehab - Index of the menu item, starting at zero, set by the application. 29154f38fcaSMauro Carvalho Chehab * - union { 29254f38fcaSMauro Carvalho Chehab - (anonymous) 29354f38fcaSMauro Carvalho Chehab * - __u8 29454f38fcaSMauro Carvalho Chehab - ``name``\ [32] 29554f38fcaSMauro Carvalho Chehab - Name of the menu item, a NUL-terminated ASCII string. This 29654f38fcaSMauro Carvalho Chehab information is intended for the user. This field is valid for 29754f38fcaSMauro Carvalho Chehab ``V4L2_CTRL_TYPE_MENU`` type controls. 29854f38fcaSMauro Carvalho Chehab * - __s64 29954f38fcaSMauro Carvalho Chehab - ``value`` 30054f38fcaSMauro Carvalho Chehab - Value of the integer menu item. This field is valid for 30154f38fcaSMauro Carvalho Chehab ``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls. 30254f38fcaSMauro Carvalho Chehab * - } 30354f38fcaSMauro Carvalho Chehab - 30454f38fcaSMauro Carvalho Chehab * - __u32 30554f38fcaSMauro Carvalho Chehab - ``reserved`` 30654f38fcaSMauro Carvalho Chehab - Reserved for future extensions. Drivers must set the array to 30754f38fcaSMauro Carvalho Chehab zero. 30854f38fcaSMauro Carvalho Chehab 30954f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_ctrl_type 31054f38fcaSMauro Carvalho Chehab 311fea13a69SMauro Carvalho Chehab.. raw:: latex 312fea13a69SMauro Carvalho Chehab 313fea13a69SMauro Carvalho Chehab \footnotesize 314fea13a69SMauro Carvalho Chehab 315fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{6.5cm}|p{1.5cm}|p{1.1cm}|p{1.5cm}|p{6.8cm}| 316fea13a69SMauro Carvalho Chehab 31754f38fcaSMauro Carvalho Chehab.. cssclass:: longtable 31854f38fcaSMauro Carvalho Chehab 31954f38fcaSMauro Carvalho Chehab.. flat-table:: enum v4l2_ctrl_type 32054f38fcaSMauro Carvalho Chehab :header-rows: 1 32154f38fcaSMauro Carvalho Chehab :stub-columns: 0 32254f38fcaSMauro Carvalho Chehab :widths: 30 5 5 5 55 32354f38fcaSMauro Carvalho Chehab 32454f38fcaSMauro Carvalho Chehab * - Type 32554f38fcaSMauro Carvalho Chehab - ``minimum`` 32654f38fcaSMauro Carvalho Chehab - ``step`` 32754f38fcaSMauro Carvalho Chehab - ``maximum`` 32854f38fcaSMauro Carvalho Chehab - Description 32954f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_INTEGER`` 33054f38fcaSMauro Carvalho Chehab - any 33154f38fcaSMauro Carvalho Chehab - any 33254f38fcaSMauro Carvalho Chehab - any 33354f38fcaSMauro Carvalho Chehab - An integer-valued control ranging from minimum to maximum 33454f38fcaSMauro Carvalho Chehab inclusive. The step value indicates the increment between values. 33554f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_BOOLEAN`` 33654f38fcaSMauro Carvalho Chehab - 0 33754f38fcaSMauro Carvalho Chehab - 1 33854f38fcaSMauro Carvalho Chehab - 1 33954f38fcaSMauro Carvalho Chehab - A boolean-valued control. Zero corresponds to "disabled", and one 34054f38fcaSMauro Carvalho Chehab means "enabled". 34154f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_MENU`` 34254f38fcaSMauro Carvalho Chehab - ≥ 0 34354f38fcaSMauro Carvalho Chehab - 1 34454f38fcaSMauro Carvalho Chehab - N-1 34554f38fcaSMauro Carvalho Chehab - The control has a menu of N choices. The names of the menu items 34654f38fcaSMauro Carvalho Chehab can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. 34754f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_INTEGER_MENU`` 34854f38fcaSMauro Carvalho Chehab - ≥ 0 34954f38fcaSMauro Carvalho Chehab - 1 35054f38fcaSMauro Carvalho Chehab - N-1 35154f38fcaSMauro Carvalho Chehab - The control has a menu of N choices. The values of the menu items 35254f38fcaSMauro Carvalho Chehab can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is 35354f38fcaSMauro Carvalho Chehab similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings, 35454f38fcaSMauro Carvalho Chehab the menu items are signed 64-bit integers. 35554f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_BITMASK`` 35654f38fcaSMauro Carvalho Chehab - 0 35754f38fcaSMauro Carvalho Chehab - n/a 35854f38fcaSMauro Carvalho Chehab - any 35954f38fcaSMauro Carvalho Chehab - A bitmask field. The maximum value is the set of bits that can be 36054f38fcaSMauro Carvalho Chehab used, all other bits are to be 0. The maximum value is interpreted 36154f38fcaSMauro Carvalho Chehab as a __u32, allowing the use of bit 31 in the bitmask. 36254f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_BUTTON`` 36354f38fcaSMauro Carvalho Chehab - 0 36454f38fcaSMauro Carvalho Chehab - 0 36554f38fcaSMauro Carvalho Chehab - 0 36654f38fcaSMauro Carvalho Chehab - A control which performs an action when set. Drivers must ignore 36754f38fcaSMauro Carvalho Chehab the value passed with ``VIDIOC_S_CTRL`` and return an ``EACCES`` error 36854f38fcaSMauro Carvalho Chehab code on a ``VIDIOC_G_CTRL`` attempt. 36954f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_INTEGER64`` 37054f38fcaSMauro Carvalho Chehab - any 37154f38fcaSMauro Carvalho Chehab - any 37254f38fcaSMauro Carvalho Chehab - any 37354f38fcaSMauro Carvalho Chehab - A 64-bit integer valued control. Minimum, maximum and step size 37454f38fcaSMauro Carvalho Chehab cannot be queried using ``VIDIOC_QUERYCTRL``. Only 37554f38fcaSMauro Carvalho Chehab ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step 37654f38fcaSMauro Carvalho Chehab values, they should be interpreted as n/a when using 37754f38fcaSMauro Carvalho Chehab ``VIDIOC_QUERYCTRL``. 37854f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_STRING`` 37954f38fcaSMauro Carvalho Chehab - ≥ 0 38054f38fcaSMauro Carvalho Chehab - ≥ 1 38154f38fcaSMauro Carvalho Chehab - ≥ 0 38254f38fcaSMauro Carvalho Chehab - The minimum and maximum string lengths. The step size means that 38354f38fcaSMauro Carvalho Chehab the string must be (minimum + N * step) characters long for N ≥ 0. 38454f38fcaSMauro Carvalho Chehab These lengths do not include the terminating zero, so in order to 38554f38fcaSMauro Carvalho Chehab pass a string of length 8 to 38654f38fcaSMauro Carvalho Chehab :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to 38754f38fcaSMauro Carvalho Chehab set the ``size`` field of struct 38854f38fcaSMauro Carvalho Chehab :c:type:`v4l2_ext_control` to 9. For 38954f38fcaSMauro Carvalho Chehab :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set 39054f38fcaSMauro Carvalho Chehab the ``size`` field to ``maximum`` + 1. Which character encoding is 39154f38fcaSMauro Carvalho Chehab used will depend on the string control itself and should be part 39254f38fcaSMauro Carvalho Chehab of the control documentation. 39354f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_CTRL_CLASS`` 39454f38fcaSMauro Carvalho Chehab - n/a 39554f38fcaSMauro Carvalho Chehab - n/a 39654f38fcaSMauro Carvalho Chehab - n/a 39754f38fcaSMauro Carvalho Chehab - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a 39854f38fcaSMauro Carvalho Chehab control ID equal to a control class code (see :ref:`ctrl-class`) 39954f38fcaSMauro Carvalho Chehab + 1, the ioctl returns the name of the control class and this 40054f38fcaSMauro Carvalho Chehab control type. Older drivers which do not support this feature 40154f38fcaSMauro Carvalho Chehab return an ``EINVAL`` error code. 40254f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_U8`` 40354f38fcaSMauro Carvalho Chehab - any 40454f38fcaSMauro Carvalho Chehab - any 40554f38fcaSMauro Carvalho Chehab - any 40654f38fcaSMauro Carvalho Chehab - An unsigned 8-bit valued control ranging from minimum to maximum 40754f38fcaSMauro Carvalho Chehab inclusive. The step value indicates the increment between values. 40854f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_U16`` 40954f38fcaSMauro Carvalho Chehab - any 41054f38fcaSMauro Carvalho Chehab - any 41154f38fcaSMauro Carvalho Chehab - any 41254f38fcaSMauro Carvalho Chehab - An unsigned 16-bit valued control ranging from minimum to maximum 41354f38fcaSMauro Carvalho Chehab inclusive. The step value indicates the increment between values. 41454f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_U32`` 41554f38fcaSMauro Carvalho Chehab - any 41654f38fcaSMauro Carvalho Chehab - any 41754f38fcaSMauro Carvalho Chehab - any 41854f38fcaSMauro Carvalho Chehab - An unsigned 32-bit valued control ranging from minimum to maximum 41954f38fcaSMauro Carvalho Chehab inclusive. The step value indicates the increment between values. 420118f3e15SEzequiel Garcia * - ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION`` 42154f38fcaSMauro Carvalho Chehab - n/a 42254f38fcaSMauro Carvalho Chehab - n/a 42354f38fcaSMauro Carvalho Chehab - n/a 424118f3e15SEzequiel Garcia - A struct :c:type:`v4l2_ctrl_mpeg2_quantisation`, containing MPEG-2 425118f3e15SEzequiel Garcia quantisation matrices for stateless video decoders. 426f329e21eSEzequiel Garcia * - ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE`` 427f329e21eSEzequiel Garcia - n/a 428f329e21eSEzequiel Garcia - n/a 429f329e21eSEzequiel Garcia - n/a 430f329e21eSEzequiel Garcia - A struct :c:type:`v4l2_ctrl_mpeg2_sequence`, containing MPEG-2 431f329e21eSEzequiel Garcia sequence parameters for stateless video decoders. 432f329e21eSEzequiel Garcia * - ``V4L2_CTRL_TYPE_MPEG2_PICTURE`` 433f329e21eSEzequiel Garcia - n/a 434f329e21eSEzequiel Garcia - n/a 435f329e21eSEzequiel Garcia - n/a 436f329e21eSEzequiel Garcia - A struct :c:type:`v4l2_ctrl_mpeg2_picture`, containing MPEG-2 437f329e21eSEzequiel Garcia picture parameters for stateless video decoders. 43854f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_AREA`` 43954f38fcaSMauro Carvalho Chehab - n/a 44054f38fcaSMauro Carvalho Chehab - n/a 44154f38fcaSMauro Carvalho Chehab - n/a 44254f38fcaSMauro Carvalho Chehab - A struct :c:type:`v4l2_area`, containing the width and the height 44354f38fcaSMauro Carvalho Chehab of a rectangular area. Units depend on the use case. 44454f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_H264_SPS`` 44554f38fcaSMauro Carvalho Chehab - n/a 44654f38fcaSMauro Carvalho Chehab - n/a 44754f38fcaSMauro Carvalho Chehab - n/a 44854f38fcaSMauro Carvalho Chehab - A struct :c:type:`v4l2_ctrl_h264_sps`, containing H264 44954f38fcaSMauro Carvalho Chehab sequence parameters for stateless video decoders. 45054f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_H264_PPS`` 45154f38fcaSMauro Carvalho Chehab - n/a 45254f38fcaSMauro Carvalho Chehab - n/a 45354f38fcaSMauro Carvalho Chehab - n/a 45454f38fcaSMauro Carvalho Chehab - A struct :c:type:`v4l2_ctrl_h264_pps`, containing H264 45554f38fcaSMauro Carvalho Chehab picture parameters for stateless video decoders. 45654f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX`` 45754f38fcaSMauro Carvalho Chehab - n/a 45854f38fcaSMauro Carvalho Chehab - n/a 45954f38fcaSMauro Carvalho Chehab - n/a 46054f38fcaSMauro Carvalho Chehab - A struct :c:type:`v4l2_ctrl_h264_scaling_matrix`, containing H264 46154f38fcaSMauro Carvalho Chehab scaling matrices for stateless video decoders. 46254f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS`` 46354f38fcaSMauro Carvalho Chehab - n/a 46454f38fcaSMauro Carvalho Chehab - n/a 46554f38fcaSMauro Carvalho Chehab - n/a 46654f38fcaSMauro Carvalho Chehab - A struct :c:type:`v4l2_ctrl_h264_slice_params`, containing H264 46754f38fcaSMauro Carvalho Chehab slice parameters for stateless video decoders. 46854f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS`` 46954f38fcaSMauro Carvalho Chehab - n/a 47054f38fcaSMauro Carvalho Chehab - n/a 47154f38fcaSMauro Carvalho Chehab - n/a 47254f38fcaSMauro Carvalho Chehab - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264 47354f38fcaSMauro Carvalho Chehab decode parameters for stateless video decoders. 4744a85d1cbSHans Verkuil * - ``V4L2_CTRL_TYPE_FWHT_PARAMS`` 4754a85d1cbSHans Verkuil - n/a 4764a85d1cbSHans Verkuil - n/a 4774a85d1cbSHans Verkuil - n/a 4784a85d1cbSHans Verkuil - A struct :c:type:`v4l2_ctrl_fwht_params`, containing FWHT 4794a85d1cbSHans Verkuil parameters for stateless video decoders. 48054f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_HEVC_SPS`` 48154f38fcaSMauro Carvalho Chehab - n/a 48254f38fcaSMauro Carvalho Chehab - n/a 48354f38fcaSMauro Carvalho Chehab - n/a 48454f38fcaSMauro Carvalho Chehab - A struct :c:type:`v4l2_ctrl_hevc_sps`, containing HEVC Sequence 48554f38fcaSMauro Carvalho Chehab Parameter Set for stateless video decoders. 48654f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_HEVC_PPS`` 48754f38fcaSMauro Carvalho Chehab - n/a 48854f38fcaSMauro Carvalho Chehab - n/a 48954f38fcaSMauro Carvalho Chehab - n/a 49054f38fcaSMauro Carvalho Chehab - A struct :c:type:`v4l2_ctrl_hevc_pps`, containing HEVC Picture 49154f38fcaSMauro Carvalho Chehab Parameter Set for stateless video decoders. 49254f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS`` 49354f38fcaSMauro Carvalho Chehab - n/a 49454f38fcaSMauro Carvalho Chehab - n/a 49554f38fcaSMauro Carvalho Chehab - n/a 49654f38fcaSMauro Carvalho Chehab - A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC 49754f38fcaSMauro Carvalho Chehab slice parameters for stateless video decoders. 4987ba59fb6SBenjamin Gaignard * - ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX`` 4997ba59fb6SBenjamin Gaignard - n/a 5007ba59fb6SBenjamin Gaignard - n/a 5017ba59fb6SBenjamin Gaignard - n/a 5027ba59fb6SBenjamin Gaignard - A struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`, containing HEVC 5037ba59fb6SBenjamin Gaignard scaling matrix for stateless video decoders. 504363240ceSEzequiel Garcia * - ``V4L2_CTRL_TYPE_VP8_FRAME`` 505363240ceSEzequiel Garcia - n/a 506363240ceSEzequiel Garcia - n/a 507363240ceSEzequiel Garcia - n/a 508363240ceSEzequiel Garcia - A struct :c:type:`v4l2_ctrl_vp8_frame`, containing VP8 509363240ceSEzequiel Garcia frame parameters for stateless video decoders. 510d395a78dSBenjamin Gaignard * - ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS`` 511d395a78dSBenjamin Gaignard - n/a 512d395a78dSBenjamin Gaignard - n/a 513d395a78dSBenjamin Gaignard - n/a 514d395a78dSBenjamin Gaignard - A struct :c:type:`v4l2_ctrl_hevc_decode_params`, containing HEVC 515d395a78dSBenjamin Gaignard decoding parameters for stateless video decoders. 516b88dbe38SAndrzej Pietrasiewicz * - ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR`` 517b88dbe38SAndrzej Pietrasiewicz - n/a 518b88dbe38SAndrzej Pietrasiewicz - n/a 519b88dbe38SAndrzej Pietrasiewicz - n/a 520b88dbe38SAndrzej Pietrasiewicz - A struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`, containing VP9 521b88dbe38SAndrzej Pietrasiewicz probabilities updates for stateless video decoders. 522b88dbe38SAndrzej Pietrasiewicz * - ``V4L2_CTRL_TYPE_VP9_FRAME`` 523b88dbe38SAndrzej Pietrasiewicz - n/a 524b88dbe38SAndrzej Pietrasiewicz - n/a 525b88dbe38SAndrzej Pietrasiewicz - n/a 526b88dbe38SAndrzej Pietrasiewicz - A struct :c:type:`v4l2_ctrl_vp9_frame`, containing VP9 527b88dbe38SAndrzej Pietrasiewicz frame decode parameters for stateless video decoders. 528*9de30f57SDaniel Almeida * - ``V4L2_CTRL_TYPE_AV1_SEQUENCE`` 529*9de30f57SDaniel Almeida - n/a 530*9de30f57SDaniel Almeida - n/a 531*9de30f57SDaniel Almeida - n/a 532*9de30f57SDaniel Almeida - A struct :c:type:`v4l2_ctrl_av1_sequence`, containing AV1 Sequence OBU 533*9de30f57SDaniel Almeida decoding parameters for stateless video decoders. 534*9de30f57SDaniel Almeida * - ``V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY`` 535*9de30f57SDaniel Almeida - n/a 536*9de30f57SDaniel Almeida - n/a 537*9de30f57SDaniel Almeida - n/a 538*9de30f57SDaniel Almeida - A struct :c:type:`v4l2_ctrl_av1_tile_group_entry`, containing AV1 Tile Group 539*9de30f57SDaniel Almeida OBU decoding parameters for stateless video decoders. 540*9de30f57SDaniel Almeida * - ``V4L2_CTRL_TYPE_AV1_FRAME`` 541*9de30f57SDaniel Almeida - n/a 542*9de30f57SDaniel Almeida - n/a 543*9de30f57SDaniel Almeida - n/a 544*9de30f57SDaniel Almeida - A struct :c:type:`v4l2_ctrl_av1_frame`, containing AV1 Frame/Frame 545*9de30f57SDaniel Almeida Header OBU decoding parameters for stateless video decoders. 546*9de30f57SDaniel Almeida * - ``V4L2_CTRL_TYPE_AV1_FILM_GRAIN`` 547*9de30f57SDaniel Almeida - n/a 548*9de30f57SDaniel Almeida - n/a 549*9de30f57SDaniel Almeida - n/a 550*9de30f57SDaniel Almeida - A struct :c:type:`v4l2_ctrl_av1_film_grain`, containing AV1 Film Grain 551*9de30f57SDaniel Almeida parameters for stateless video decoders. 55254f38fcaSMauro Carvalho Chehab 553fea13a69SMauro Carvalho Chehab.. raw:: latex 554fea13a69SMauro Carvalho Chehab 555fea13a69SMauro Carvalho Chehab \normalsize 55654f38fcaSMauro Carvalho Chehab 557fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{7.3cm}|p{1.8cm}|p{8.2cm}| 558fea13a69SMauro Carvalho Chehab 55954f38fcaSMauro Carvalho Chehab.. cssclass:: longtable 56054f38fcaSMauro Carvalho Chehab 561c4a1bff9SMauro Carvalho Chehab.. _control-flags: 562c4a1bff9SMauro Carvalho Chehab 56354f38fcaSMauro Carvalho Chehab.. flat-table:: Control Flags 56454f38fcaSMauro Carvalho Chehab :header-rows: 0 56554f38fcaSMauro Carvalho Chehab :stub-columns: 0 56654f38fcaSMauro Carvalho Chehab :widths: 3 1 4 56754f38fcaSMauro Carvalho Chehab 56854f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_FLAG_DISABLED`` 56954f38fcaSMauro Carvalho Chehab - 0x0001 57054f38fcaSMauro Carvalho Chehab - This control is permanently disabled and should be ignored by the 57154f38fcaSMauro Carvalho Chehab application. Any attempt to change the control will result in an 57254f38fcaSMauro Carvalho Chehab ``EINVAL`` error code. 57354f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_FLAG_GRABBED`` 57454f38fcaSMauro Carvalho Chehab - 0x0002 57554f38fcaSMauro Carvalho Chehab - This control is temporarily unchangeable, for example because 57654f38fcaSMauro Carvalho Chehab another application took over control of the respective resource. 57754f38fcaSMauro Carvalho Chehab Such controls may be displayed specially in a user interface. 57854f38fcaSMauro Carvalho Chehab Attempts to change the control may result in an ``EBUSY`` error code. 57954f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_FLAG_READ_ONLY`` 58054f38fcaSMauro Carvalho Chehab - 0x0004 58154f38fcaSMauro Carvalho Chehab - This control is permanently readable only. Any attempt to change 58254f38fcaSMauro Carvalho Chehab the control will result in an ``EINVAL`` error code. 58354f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_FLAG_UPDATE`` 58454f38fcaSMauro Carvalho Chehab - 0x0008 58554f38fcaSMauro Carvalho Chehab - A hint that changing this control may affect the value of other 58654f38fcaSMauro Carvalho Chehab controls within the same control class. Applications should update 58754f38fcaSMauro Carvalho Chehab their user interface accordingly. 58854f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_FLAG_INACTIVE`` 58954f38fcaSMauro Carvalho Chehab - 0x0010 59054f38fcaSMauro Carvalho Chehab - This control is not applicable to the current configuration and 59154f38fcaSMauro Carvalho Chehab should be displayed accordingly in a user interface. For example 59254f38fcaSMauro Carvalho Chehab the flag may be set on a MPEG audio level 2 bitrate control when 59354f38fcaSMauro Carvalho Chehab MPEG audio encoding level 1 was selected with another control. 59454f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_FLAG_SLIDER`` 59554f38fcaSMauro Carvalho Chehab - 0x0020 59654f38fcaSMauro Carvalho Chehab - A hint that this control is best represented as a slider-like 59754f38fcaSMauro Carvalho Chehab element in a user interface. 59854f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_FLAG_WRITE_ONLY`` 59954f38fcaSMauro Carvalho Chehab - 0x0040 60054f38fcaSMauro Carvalho Chehab - This control is permanently writable only. Any attempt to read the 60154f38fcaSMauro Carvalho Chehab control will result in an ``EACCES`` error code error code. This flag 60254f38fcaSMauro Carvalho Chehab is typically present for relative controls or action controls 60354f38fcaSMauro Carvalho Chehab where writing a value will cause the device to carry out a given 60454f38fcaSMauro Carvalho Chehab action (e. g. motor control) but no meaningful value can be 60554f38fcaSMauro Carvalho Chehab returned. 60654f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_FLAG_VOLATILE`` 60754f38fcaSMauro Carvalho Chehab - 0x0080 60854f38fcaSMauro Carvalho Chehab - This control is volatile, which means that the value of the 60954f38fcaSMauro Carvalho Chehab control changes continuously. A typical example would be the 61054f38fcaSMauro Carvalho Chehab current gain value if the device is in auto-gain mode. In such a 61154f38fcaSMauro Carvalho Chehab case the hardware calculates the gain value based on the lighting 61254f38fcaSMauro Carvalho Chehab conditions which can change over time. 61354f38fcaSMauro Carvalho Chehab 61454f38fcaSMauro Carvalho Chehab .. note:: 61554f38fcaSMauro Carvalho Chehab 61654f38fcaSMauro Carvalho Chehab Setting a new value for a volatile control will be ignored 61754f38fcaSMauro Carvalho Chehab unless 61854f38fcaSMauro Carvalho Chehab :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>` 61954f38fcaSMauro Carvalho Chehab is also set. 62054f38fcaSMauro Carvalho Chehab Setting a new value for a volatile control will *never* trigger a 62154f38fcaSMauro Carvalho Chehab :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event. 62254f38fcaSMauro Carvalho Chehab * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` 62354f38fcaSMauro Carvalho Chehab - 0x0100 62454f38fcaSMauro Carvalho Chehab - This control has a pointer type, so its value has to be accessed 62554f38fcaSMauro Carvalho Chehab using one of the pointer fields of struct 62654f38fcaSMauro Carvalho Chehab :c:type:`v4l2_ext_control`. This flag is set 62754f38fcaSMauro Carvalho Chehab for controls that are an array, string, or have a compound type. 62854f38fcaSMauro Carvalho Chehab In all cases you have to set a pointer to memory containing the 62954f38fcaSMauro Carvalho Chehab payload of the control. 63054f38fcaSMauro Carvalho Chehab * .. _FLAG_EXECUTE_ON_WRITE: 63154f38fcaSMauro Carvalho Chehab 63254f38fcaSMauro Carvalho Chehab - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` 63354f38fcaSMauro Carvalho Chehab - 0x0200 63454f38fcaSMauro Carvalho Chehab - The value provided to the control will be propagated to the driver 63554f38fcaSMauro Carvalho Chehab even if it remains constant. This is required when the control 63654f38fcaSMauro Carvalho Chehab represents an action on the hardware. For example: clearing an 63754f38fcaSMauro Carvalho Chehab error flag or triggering the flash. All the controls of the type 63854f38fcaSMauro Carvalho Chehab ``V4L2_CTRL_TYPE_BUTTON`` have this flag set. 63954f38fcaSMauro Carvalho Chehab * .. _FLAG_MODIFY_LAYOUT: 64054f38fcaSMauro Carvalho Chehab 64154f38fcaSMauro Carvalho Chehab - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` 64254f38fcaSMauro Carvalho Chehab - 0x0400 64354f38fcaSMauro Carvalho Chehab - Changing this control value may modify the layout of the 64454f38fcaSMauro Carvalho Chehab buffer (for video devices) or the media bus format (for sub-devices). 64554f38fcaSMauro Carvalho Chehab 64654f38fcaSMauro Carvalho Chehab A typical example would be the ``V4L2_CID_ROTATE`` control. 64754f38fcaSMauro Carvalho Chehab 64854f38fcaSMauro Carvalho Chehab Note that typically controls with this flag will also set the 64954f38fcaSMauro Carvalho Chehab ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or 65054f38fcaSMauro Carvalho Chehab streaming is in progress since most drivers do not support changing 65154f38fcaSMauro Carvalho Chehab the format in that case. 65264fe675eSHans Verkuil * - ``V4L2_CTRL_FLAG_DYNAMIC_ARRAY`` 65364fe675eSHans Verkuil - 0x0800 65464fe675eSHans Verkuil - This control is a dynamically sized 1-dimensional array. It 65564fe675eSHans Verkuil behaves the same as a regular array, except that the number 65664fe675eSHans Verkuil of elements as reported by the ``elems`` field is between 1 and 65764fe675eSHans Verkuil ``dims[0]``. So setting the control with a differently sized 65864fe675eSHans Verkuil array will change the ``elems`` field when the control is 65964fe675eSHans Verkuil queried afterwards. 66054f38fcaSMauro Carvalho Chehab 66154f38fcaSMauro Carvalho ChehabReturn Value 66254f38fcaSMauro Carvalho Chehab============ 66354f38fcaSMauro Carvalho Chehab 66454f38fcaSMauro Carvalho ChehabOn success 0 is returned, on error -1 and the ``errno`` variable is set 66554f38fcaSMauro Carvalho Chehabappropriately. The generic error codes are described at the 66654f38fcaSMauro Carvalho Chehab:ref:`Generic Error Codes <gen-errors>` chapter. 66754f38fcaSMauro Carvalho Chehab 66854f38fcaSMauro Carvalho ChehabEINVAL 66954f38fcaSMauro Carvalho Chehab The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is 67054f38fcaSMauro Carvalho Chehab invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id`` 67154f38fcaSMauro Carvalho Chehab is invalid or ``index`` is out of range (less than ``minimum`` or 67254f38fcaSMauro Carvalho Chehab greater than ``maximum``) or this particular menu item is not 67354f38fcaSMauro Carvalho Chehab supported by the driver. 67454f38fcaSMauro Carvalho Chehab 67554f38fcaSMauro Carvalho ChehabEACCES 67654f38fcaSMauro Carvalho Chehab An attempt was made to read a write-only control. 67754f38fcaSMauro Carvalho Chehab 67854f38fcaSMauro Carvalho Chehab.. [#f1] 67954f38fcaSMauro Carvalho Chehab ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers 68054f38fcaSMauro Carvalho Chehab can skip predefined controls not supported by the hardware (although 68154f38fcaSMauro Carvalho Chehab returning ``EINVAL`` would do as well), or disable predefined and private 68254f38fcaSMauro Carvalho Chehab controls after hardware detection without the trouble of reordering 68354f38fcaSMauro Carvalho Chehab control arrays and indices (``EINVAL`` cannot be used to skip private 68454f38fcaSMauro Carvalho Chehab controls because it would prematurely end the enumeration). 685