diff options
Diffstat (limited to 'Documentation/DocBook/v4l/vidioc-queryctrl.xml')
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-queryctrl.xml | 434 |
1 files changed, 0 insertions, 434 deletions
diff --git a/Documentation/DocBook/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/v4l/vidioc-queryctrl.xml deleted file mode 100644 index 0d5e828..0000000 --- a/Documentation/DocBook/v4l/vidioc-queryctrl.xml +++ /dev/null @@ -1,434 +0,0 @@ -<refentry id="vidioc-queryctrl"> - <refmeta> - <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_QUERYCTRL</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_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_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_BASE_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 control, or <errorcode>EINVAL</errorcode> if there is -none. Drivers which do not support this flag yet always return -<errorcode>EINVAL</errorcode>.</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>&v4l2-ctrl-type;</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 <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the -lowest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> controls. -For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value -gives the minimum length of the string. This length <emphasis>does not include the terminating -zero</emphasis>. It may not be valid for any other type of control, including -<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a -signed value.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>maximum</structfield></entry> - <entry>Maximum value, inclusive. This field gives an upper -bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the -highest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> -controls. -For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the maximum value -gives the maximum length of the string. This length <emphasis>does not include the terminating -zero</emphasis>. It may not be valid for any other type of control, including -<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a -signed value.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>step</structfield></entry> - <entry><para>This field gives a step size for -<constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. For -<constant>V4L2_CTRL_TYPE_STRING</constant> controls this field refers to -the string length that has to be a multiple of this step size. -It may not be valid for any other type of control, including -<constant>V4L2_CTRL_TYPE_INTEGER64</constant> -controls.</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> or <constant>_MENU</constant> control. -Not valid for other types of controls. Drivers reset controls only -when the driver is loaded, not later, in particular not when the -func-open; is called.</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-querymenu"> - <title>struct <structname>v4l2_querymenu</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 -from the respective &v4l2-queryctrl; -<structfield>id</structfield>.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Index of the menu item, starting at zero, set by - the application.</entry> - </row> - <row> - <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.</entry> - </row> - <row> - <entry>__u32</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_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>n/a</entry> - <entry>n/a</entry> - <entry>n/a</entry> - <entry>A 64-bit integer valued control. Minimum, maximum -and step size cannot be queried.</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> - </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> - </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> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> |