123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661 |
- <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> and/or array
- control, in other words controls that contain more than one value).
- 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.</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.
- </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.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_TYPE_U32</constant></entry>
- <entry>any</entry>
- <entry>any</entry>
- <entry>any</entry>
- <entry>An unsigned 32-bit valued control ranging from minimum to
- maximum inclusive. The step value indicates the increment between
- values.
- </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 it 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>
|