| <refentry id="vidioc-queryctrl"> |
| <refmeta> |
| <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</refentrytitle> |
| &manvol; |
| </refmeta> |
| |
| <refnamediv> |
| <refname>VIDIOC_QUERYCTRL</refname> |
| <refname>VIDIOC_QUERY_EXT_CTRL</refname> |
| <refname>VIDIOC_QUERYMENU</refname> |
| <refpurpose>Enumerate controls and menu control items</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <funcsynopsis> |
| <funcprototype> |
| <funcdef>int <function>ioctl</function></funcdef> |
| <paramdef>int <parameter>fd</parameter></paramdef> |
| <paramdef>int <parameter>request</parameter></paramdef> |
| <paramdef>struct v4l2_queryctrl *<parameter>argp</parameter></paramdef> |
| </funcprototype> |
| </funcsynopsis> |
| <funcsynopsis> |
| <funcprototype> |
| <funcdef>int <function>ioctl</function></funcdef> |
| <paramdef>int <parameter>fd</parameter></paramdef> |
| <paramdef>int <parameter>request</parameter></paramdef> |
| <paramdef>struct v4l2_query_ext_ctrl *<parameter>argp</parameter></paramdef> |
| </funcprototype> |
| </funcsynopsis> |
| <funcsynopsis> |
| <funcprototype> |
| <funcdef>int <function>ioctl</function></funcdef> |
| <paramdef>int <parameter>fd</parameter></paramdef> |
| <paramdef>int <parameter>request</parameter></paramdef> |
| <paramdef>struct v4l2_querymenu *<parameter>argp</parameter></paramdef> |
| </funcprototype> |
| </funcsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Arguments</title> |
| |
| <variablelist> |
| <varlistentry> |
| <term><parameter>fd</parameter></term> |
| <listitem> |
| <para>&fd;</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><parameter>request</parameter></term> |
| <listitem> |
| <para>VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><parameter>argp</parameter></term> |
| <listitem> |
| <para></para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para>To query the attributes of a control applications set the |
| <structfield>id</structfield> field of a &v4l2-queryctrl; and call the |
| <constant>VIDIOC_QUERYCTRL</constant> ioctl with a pointer to this |
| structure. The driver fills the rest of the structure or returns an |
| &EINVAL; when the <structfield>id</structfield> is invalid.</para> |
| |
| <para>It is possible to enumerate controls by calling |
| <constant>VIDIOC_QUERYCTRL</constant> with successive |
| <structfield>id</structfield> values starting from |
| <constant>V4L2_CID_BASE</constant> up to and exclusive |
| <constant>V4L2_CID_LASTP1</constant>. Drivers may return |
| <errorcode>EINVAL</errorcode> if a control in this range is not |
| supported. Further applications can enumerate private controls, which |
| are not defined in this specification, by starting at |
| <constant>V4L2_CID_PRIVATE_BASE</constant> and incrementing |
| <structfield>id</structfield> until the driver returns |
| <errorcode>EINVAL</errorcode>.</para> |
| |
| <para>In both cases, when the driver sets the |
| <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag in the |
| <structfield>flags</structfield> field this control is permanently |
| disabled and should be ignored by the application.<footnote> |
| <para><constant>V4L2_CTRL_FLAG_DISABLED</constant> was |
| intended for two purposes: Drivers can skip predefined controls not |
| supported by the hardware (although returning EINVAL would do as |
| well), or disable predefined and private controls after hardware |
| detection without the trouble of reordering control arrays and indices |
| (EINVAL cannot be used to skip private controls because it would |
| prematurely end the enumeration).</para></footnote></para> |
| |
| <para>When the application ORs <structfield>id</structfield> with |
| <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver returns the |
| next supported non-compound control, or <errorcode>EINVAL</errorcode> |
| if there is none. In addition, the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> |
| flag can be specified to enumerate all compound controls (i.e. controls |
| with type ≥ <constant>V4L2_CTRL_COMPOUND_TYPES</constant>). Specify both |
| <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> and |
| <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> in order to enumerate |
| all controls, compound or not. Drivers which do not support these flags yet |
| always return <errorcode>EINVAL</errorcode>.</para> |
| |
| <para>The <constant>VIDIOC_QUERY_EXT_CTRL</constant> ioctl was |
| introduced in order to better support controls that can use compound |
| types, and to expose additional control information that cannot be |
| returned in &v4l2-queryctrl; since that structure is full.</para> |
| |
| <para><constant>VIDIOC_QUERY_EXT_CTRL</constant> is used in the |
| same way as <constant>VIDIOC_QUERYCTRL</constant>, except that the |
| <structfield>reserved</structfield> array must be zeroed as well.</para> |
| |
| <para>Additional information is required for menu controls: the |
| names of the menu items. To query them applications set the |
| <structfield>id</structfield> and <structfield>index</structfield> |
| fields of &v4l2-querymenu; and call the |
| <constant>VIDIOC_QUERYMENU</constant> ioctl with a pointer to this |
| structure. The driver fills the rest of the structure or returns an |
| &EINVAL; when the <structfield>id</structfield> or |
| <structfield>index</structfield> is invalid. Menu items are enumerated |
| by calling <constant>VIDIOC_QUERYMENU</constant> with successive |
| <structfield>index</structfield> values from &v4l2-queryctrl; |
| <structfield>minimum</structfield> to |
| <structfield>maximum</structfield>, inclusive. Note that it is possible |
| for <constant>VIDIOC_QUERYMENU</constant> to return an &EINVAL; for some |
| indices between <structfield>minimum</structfield> and <structfield>maximum</structfield>. |
| In that case that particular menu item is not supported by this driver. Also note that |
| the <structfield>minimum</structfield> value is not necessarily 0.</para> |
| |
| <para>See also the examples in <xref linkend="control" />.</para> |
| |
| <table pgwide="1" frame="none" id="v4l2-queryctrl"> |
| <title>struct <structname>v4l2_queryctrl</structname></title> |
| <tgroup cols="3"> |
| &cs-str; |
| <tbody valign="top"> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>id</structfield></entry> |
| <entry>Identifies the control, set by the application. See |
| <xref linkend="control-id" /> for predefined IDs. When the ID is ORed |
| with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and returns |
| the first control with a higher ID. Drivers which do not support this |
| flag yet always return an &EINVAL;.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>type</structfield></entry> |
| <entry>Type of control, see <xref |
| linkend="v4l2-ctrl-type" />.</entry> |
| </row> |
| <row> |
| <entry>__u8</entry> |
| <entry><structfield>name</structfield>[32]</entry> |
| <entry>Name of the control, a NUL-terminated ASCII |
| string. This information is intended for the user.</entry> |
| </row> |
| <row> |
| <entry>__s32</entry> |
| <entry><structfield>minimum</structfield></entry> |
| <entry>Minimum value, inclusive. This field gives a lower |
| bound for the control. See &v4l2-ctrl-type; how the minimum value is to |
| be used for each possible control type. Note that this a signed 32-bit value.</entry> |
| </row> |
| <row> |
| <entry>__s32</entry> |
| <entry><structfield>maximum</structfield></entry> |
| <entry>Maximum value, inclusive. This field gives an upper |
| bound for the control. See &v4l2-ctrl-type; how the maximum value is to |
| be used for each possible control type. Note that this a signed 32-bit value.</entry> |
| </row> |
| <row> |
| <entry>__s32</entry> |
| <entry><structfield>step</structfield></entry> |
| <entry><para>This field gives a step size for the control. |
| See &v4l2-ctrl-type; how the step value is to be used for each possible |
| control type. Note that this an unsigned 32-bit value. |
| </para><para>Generally drivers should not scale hardware |
| control values. It may be necessary for example when the |
| <structfield>name</structfield> or <structfield>id</structfield> imply |
| a particular unit and the hardware actually accepts only multiples of |
| said unit. If so, drivers must take care values are properly rounded |
| when scaling, such that errors will not accumulate on repeated |
| read-write cycles.</para><para>This field gives the smallest change of |
| an integer control actually affecting hardware. Often the information |
| is needed when the user can change controls by keyboard or GUI |
| buttons, rather than a slider. When for example a hardware register |
| accepts values 0-511 and the driver reports 0-65535, step should be |
| 128.</para><para>Note that although signed, the step value is supposed to |
| be always positive.</para></entry> |
| </row> |
| <row> |
| <entry>__s32</entry> |
| <entry><structfield>default_value</structfield></entry> |
| <entry>The default value of a |
| <constant>V4L2_CTRL_TYPE_INTEGER</constant>, |
| <constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>, |
| <constant>_MENU</constant> or <constant>_INTEGER_MENU</constant> control. |
| Not valid for other types of controls. |
| Note that drivers reset controls to their default value only when the |
| driver is first loaded, never afterwards.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>flags</structfield></entry> |
| <entry>Control flags, see <xref |
| linkend="control-flags" />.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>reserved</structfield>[2]</entry> |
| <entry>Reserved for future extensions. Drivers must set |
| the array to zero.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <table pgwide="1" frame="none" id="v4l2-query-ext-ctrl"> |
| <title>struct <structname>v4l2_query_ext_ctrl</structname></title> |
| <tgroup cols="3"> |
| &cs-str; |
| <tbody valign="top"> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>id</structfield></entry> |
| <entry>Identifies the control, set by the application. See |
| <xref linkend="control-id" /> for predefined IDs. When the ID is ORed |
| with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver clears the |
| flag and returns the first non-compound control with a higher ID. When the |
| ID is ORed with <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> the driver |
| clears the flag and returns the first compound control with a higher ID. |
| Set both to get the first control (compound or not) with a higher ID.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>type</structfield></entry> |
| <entry>Type of control, see <xref |
| linkend="v4l2-ctrl-type" />.</entry> |
| </row> |
| <row> |
| <entry>char</entry> |
| <entry><structfield>name</structfield>[32]</entry> |
| <entry>Name of the control, a NUL-terminated ASCII |
| string. This information is intended for the user.</entry> |
| </row> |
| <row> |
| <entry>__s64</entry> |
| <entry><structfield>minimum</structfield></entry> |
| <entry>Minimum value, inclusive. This field gives a lower |
| bound for the control. See &v4l2-ctrl-type; how the minimum value is to |
| be used for each possible control type. Note that this a signed 64-bit value.</entry> |
| </row> |
| <row> |
| <entry>__s64</entry> |
| <entry><structfield>maximum</structfield></entry> |
| <entry>Maximum value, inclusive. This field gives an upper |
| bound for the control. See &v4l2-ctrl-type; how the maximum value is to |
| be used for each possible control type. Note that this a signed 64-bit value.</entry> |
| </row> |
| <row> |
| <entry>__u64</entry> |
| <entry><structfield>step</structfield></entry> |
| <entry><para>This field gives a step size for the control. |
| See &v4l2-ctrl-type; how the step value is to be used for each possible |
| control type. Note that this an unsigned 64-bit value. |
| </para><para>Generally drivers should not scale hardware |
| control values. It may be necessary for example when the |
| <structfield>name</structfield> or <structfield>id</structfield> imply |
| a particular unit and the hardware actually accepts only multiples of |
| said unit. If so, drivers must take care values are properly rounded |
| when scaling, such that errors will not accumulate on repeated |
| read-write cycles.</para><para>This field gives the smallest change of |
| an integer control actually affecting hardware. Often the information |
| is needed when the user can change controls by keyboard or GUI |
| buttons, rather than a slider. When for example a hardware register |
| accepts values 0-511 and the driver reports 0-65535, step should be |
| 128.</para></entry> |
| </row> |
| <row> |
| <entry>__s64</entry> |
| <entry><structfield>default_value</structfield></entry> |
| <entry>The default value of a |
| <constant>V4L2_CTRL_TYPE_INTEGER</constant>, <constant>_INTEGER64</constant>, |
| <constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>, |
| <constant>_MENU</constant>, <constant>_INTEGER_MENU</constant>, |
| <constant>_U8</constant> or <constant>_U16</constant> control. |
| Not valid for other types of controls. |
| Note that drivers reset controls to their default value only when the |
| driver is first loaded, never afterwards. |
| </entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>flags</structfield></entry> |
| <entry>Control flags, see <xref |
| linkend="control-flags" />.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>elem_size</structfield></entry> |
| <entry>The size in bytes of a single element of the array. |
| Given a char pointer <constant>p</constant> to a 3-dimensional array you can find the |
| position of cell <constant>(z, y, x)</constant> as follows: |
| <constant>p + ((z * dims[1] + y) * dims[0] + x) * elem_size</constant>. <structfield>elem_size</structfield> |
| is always valid, also when the control isn't an array. For string controls |
| <structfield>elem_size</structfield> is equal to <structfield>maximum + 1</structfield>. |
| </entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>elems</structfield></entry> |
| <entry>The number of elements in the N-dimensional array. If this control |
| is not an array, then <structfield>elems</structfield> is 1. The <structfield>elems</structfield> |
| field can never be 0.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>nr_of_dims</structfield></entry> |
| <entry>The number of dimension in the N-dimensional array. If this control |
| is not an array, then this field is 0.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>dims[V4L2_CTRL_MAX_DIMS]</structfield></entry> |
| <entry>The size of each dimension. The first <structfield>nr_of_dims</structfield> |
| elements of this array must be non-zero, all remaining elements must be zero.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>reserved</structfield>[32]</entry> |
| <entry>Reserved for future extensions. Applications and drivers |
| must set the array to zero.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <table pgwide="1" frame="none" id="v4l2-querymenu"> |
| <title>struct <structname>v4l2_querymenu</structname></title> |
| <tgroup cols="4"> |
| &cs-str; |
| <tbody valign="top"> |
| <row> |
| <entry>__u32</entry> |
| <entry></entry> |
| <entry><structfield>id</structfield></entry> |
| <entry>Identifies the control, set by the application |
| from the respective &v4l2-queryctrl; |
| <structfield>id</structfield>.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry></entry> |
| <entry><structfield>index</structfield></entry> |
| <entry>Index of the menu item, starting at zero, set by |
| the application.</entry> |
| </row> |
| <row> |
| <entry>union</entry> |
| <entry></entry> |
| <entry></entry> |
| <entry></entry> |
| </row> |
| <row> |
| <entry></entry> |
| <entry>__u8</entry> |
| <entry><structfield>name</structfield>[32]</entry> |
| <entry>Name of the menu item, a NUL-terminated ASCII |
| string. This information is intended for the user. This field is valid |
| for <constant>V4L2_CTRL_FLAG_MENU</constant> type controls.</entry> |
| </row> |
| <row> |
| <entry></entry> |
| <entry>__s64</entry> |
| <entry><structfield>value</structfield></entry> |
| <entry> |
| Value of the integer menu item. This field is valid for |
| <constant>V4L2_CTRL_FLAG_INTEGER_MENU</constant> type |
| controls. |
| </entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry></entry> |
| <entry><structfield>reserved</structfield></entry> |
| <entry>Reserved for future extensions. Drivers must set |
| the array to zero.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <table pgwide="1" frame="none" id="v4l2-ctrl-type"> |
| <title>enum v4l2_ctrl_type</title> |
| <tgroup cols="5" align="left"> |
| <colspec colwidth="30*" /> |
| <colspec colwidth="5*" align="center" /> |
| <colspec colwidth="5*" align="center" /> |
| <colspec colwidth="5*" align="center" /> |
| <colspec colwidth="55*" /> |
| <thead> |
| <row> |
| <entry>Type</entry> |
| <entry><structfield>minimum</structfield></entry> |
| <entry><structfield>step</structfield></entry> |
| <entry><structfield>maximum</structfield></entry> |
| <entry>Description</entry> |
| </row> |
| </thead> |
| <tbody valign="top"> |
| <row> |
| <entry><constant>V4L2_CTRL_TYPE_INTEGER</constant></entry> |
| <entry>any</entry> |
| <entry>any</entry> |
| <entry>any</entry> |
| <entry>An integer-valued control ranging from minimum to |
| maximum inclusive. The step value indicates the increment between |
| values which are actually different on the hardware.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_TYPE_BOOLEAN</constant></entry> |
| <entry>0</entry> |
| <entry>1</entry> |
| <entry>1</entry> |
| <entry>A boolean-valued control. Zero corresponds to |
| "disabled", and one means "enabled".</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_TYPE_MENU</constant></entry> |
| <entry>≥ 0</entry> |
| <entry>1</entry> |
| <entry>N-1</entry> |
| <entry>The control has a menu of N choices. The names of |
| the menu items can be enumerated with the |
| <constant>VIDIOC_QUERYMENU</constant> ioctl.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_TYPE_INTEGER_MENU</constant></entry> |
| <entry>≥ 0</entry> |
| <entry>1</entry> |
| <entry>N-1</entry> |
| <entry> |
| The control has a menu of N choices. The values of the |
| menu items can be enumerated with the |
| <constant>VIDIOC_QUERYMENU</constant> ioctl. This is |
| similar to <constant>V4L2_CTRL_TYPE_MENU</constant> |
| except that instead of strings, the menu items are |
| signed 64-bit integers. |
| </entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_TYPE_BITMASK</constant></entry> |
| <entry>0</entry> |
| <entry>n/a</entry> |
| <entry>any</entry> |
| <entry>A bitmask field. The maximum value is the set of bits that can |
| be used, all other bits are to be 0. The maximum value is interpreted as a __u32, |
| allowing the use of bit 31 in the bitmask.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_TYPE_BUTTON</constant></entry> |
| <entry>0</entry> |
| <entry>0</entry> |
| <entry>0</entry> |
| <entry>A control which performs an action when set. |
| Drivers must ignore the value passed with |
| <constant>VIDIOC_S_CTRL</constant> and return an &EINVAL; on a |
| <constant>VIDIOC_G_CTRL</constant> attempt.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry> |
| <entry>any</entry> |
| <entry>any</entry> |
| <entry>any</entry> |
| <entry>A 64-bit integer valued control. Minimum, maximum |
| and step size cannot be queried using <constant>VIDIOC_QUERYCTRL</constant>. |
| Only <constant>VIDIOC_QUERY_EXT_CTRL</constant> can retrieve the 64-bit |
| min/max/step values, they should be interpreted as n/a when using |
| <constant>VIDIOC_QUERYCTRL</constant>.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry> |
| <entry>≥ 0</entry> |
| <entry>≥ 1</entry> |
| <entry>≥ 0</entry> |
| <entry>The minimum and maximum string lengths. The step size |
| means that the string must be (minimum + N * step) characters long for |
| N ≥ 0. These lengths do not include the terminating zero, so in order to |
| pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the |
| <structfield>size</structfield> field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can |
| set the <structfield>size</structfield> field to <structfield>maximum</structfield> + 1. |
| Which character encoding is used will depend on the string control itself and |
| should be part of the control documentation.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant></entry> |
| <entry>n/a</entry> |
| <entry>n/a</entry> |
| <entry>n/a</entry> |
| <entry>This is not a control. When |
| <constant>VIDIOC_QUERYCTRL</constant> is called with a control ID |
| equal to a control class code (see <xref linkend="ctrl-class" />) + 1, the |
| ioctl returns the name of the control class and this control type. |
| Older drivers which do not support this feature return an |
| &EINVAL;.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_TYPE_U8</constant></entry> |
| <entry>any</entry> |
| <entry>any</entry> |
| <entry>any</entry> |
| <entry>An unsigned 8-bit valued control ranging from minimum to |
| maximum inclusive. The step value indicates the increment between |
| values which are actually different on the hardware. |
| </entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_TYPE_U16</constant></entry> |
| <entry>any</entry> |
| <entry>any</entry> |
| <entry>any</entry> |
| <entry>An unsigned 16-bit valued control ranging from minimum to |
| maximum inclusive. The step value indicates the increment between |
| values which are actually different on the hardware. |
| </entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <table pgwide="1" frame="none" id="control-flags"> |
| <title>Control Flags</title> |
| <tgroup cols="3"> |
| &cs-def; |
| <tbody valign="top"> |
| <row> |
| <entry><constant>V4L2_CTRL_FLAG_DISABLED</constant></entry> |
| <entry>0x0001</entry> |
| <entry>This control is permanently disabled and should be |
| ignored by the application. Any attempt to change the control will |
| result in an &EINVAL;.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_FLAG_GRABBED</constant></entry> |
| <entry>0x0002</entry> |
| <entry>This control is temporarily unchangeable, for |
| example because another application took over control of the |
| respective resource. Such controls may be displayed specially in a |
| user interface. Attempts to change the control may result in an |
| &EBUSY;.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_FLAG_READ_ONLY</constant></entry> |
| <entry>0x0004</entry> |
| <entry>This control is permanently readable only. Any |
| attempt to change the control will result in an &EINVAL;.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_FLAG_UPDATE</constant></entry> |
| <entry>0x0008</entry> |
| <entry>A hint that changing this control may affect the |
| value of other controls within the same control class. Applications |
| should update their user interface accordingly.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_FLAG_INACTIVE</constant></entry> |
| <entry>0x0010</entry> |
| <entry>This control is not applicable to the current |
| configuration and should be displayed accordingly in a user interface. |
| For example the flag may be set on a MPEG audio level 2 bitrate |
| control when MPEG audio encoding level 1 was selected with another |
| control.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_FLAG_SLIDER</constant></entry> |
| <entry>0x0020</entry> |
| <entry>A hint that this control is best represented as a |
| slider-like element in a user interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant></entry> |
| <entry>0x0040</entry> |
| <entry>This control is permanently writable only. Any |
| attempt to read the control will result in an &EACCES; error code. This |
| flag is typically present for relative controls or action controls where |
| writing a value will cause the device to carry out a given action |
| (⪚ motor control) but no meaningful value can be returned.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_FLAG_VOLATILE</constant></entry> |
| <entry>0x0080</entry> |
| <entry>This control is volatile, which means that the value of the control |
| changes continuously. A typical example would be the current gain value if the device |
| is in auto-gain mode. In such a case the hardware calculates the gain value based on |
| the lighting conditions which can change over time. Note that setting a new value for |
| a volatile control will have no effect and no <constant>V4L2_EVENT_CTRL_CH_VALUE</constant> |
| will be sent, unless the <constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant> flag |
| (see below) is also set. Otherwise the new value will just be ignored.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant></entry> |
| <entry>0x0100</entry> |
| <entry>This control has a pointer type, so its value has to be accessed |
| using one of the pointer fields of &v4l2-ext-control;. This flag is set for controls |
| that are an array, string, or have a compound type. In all cases you have to set a |
| pointer to memory containing the payload of the control.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant></entry> |
| <entry>0x0200</entry> |
| <entry>The value provided to the control will be propagated to the driver |
| even if remains constant. This is required when the control represents an action |
| on the hardware. For example: clearing an error flag or triggering the flash. All the |
| controls of the type <constant>V4L2_CTRL_TYPE_BUTTON</constant> have this flag set.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| </refsect1> |
| |
| <refsect1> |
| &return-value; |
| |
| <variablelist> |
| <varlistentry> |
| <term><errorcode>EINVAL</errorcode></term> |
| <listitem> |
| <para>The &v4l2-queryctrl; <structfield>id</structfield> |
| is invalid. The &v4l2-querymenu; <structfield>id</structfield> is |
| invalid or <structfield>index</structfield> is out of range (less than |
| <structfield>minimum</structfield> or greater than <structfield>maximum</structfield>) |
| or this particular menu item is not supported by the driver.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><errorcode>EACCES</errorcode></term> |
| <listitem> |
| <para>An attempt was made to read a write-only control.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| </refentry> |
