diff options
Diffstat (limited to 'v4l2-spec/vidioc-queryctrl.sgml')
| -rw-r--r-- | v4l2-spec/vidioc-queryctrl.sgml | 62 |
1 files changed, 42 insertions, 20 deletions
diff --git a/v4l2-spec/vidioc-queryctrl.sgml b/v4l2-spec/vidioc-queryctrl.sgml index 9908a964d..4876ff1a1 100644 --- a/v4l2-spec/vidioc-queryctrl.sgml +++ b/v4l2-spec/vidioc-queryctrl.sgml @@ -93,8 +93,8 @@ 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 -name of menu items. To query them applications set the + <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 @@ -106,7 +106,7 @@ by calling <constant>VIDIOC_QUERYMENU</constant> with successive <structfield>minimum</structfield> (0) to <structfield>maximum</structfield>, inclusive.</para> - <para>See also the examples in <xref linkend="control">.</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> @@ -117,7 +117,7 @@ by calling <constant>VIDIOC_QUERYMENU</constant> with successive <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 +<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> @@ -126,7 +126,7 @@ flag yet always return an &EINVAL;.</entry> <entry>&v4l2-ctrl-type;</entry> <entry><structfield>type</structfield></entry> <entry>Type of control, see <xref - linkend="v4l2-ctrl-type">.</entry> + linkend="v4l2-ctrl-type" />.</entry> </row> <row> <entry>__u8</entry> @@ -138,9 +138,12 @@ string. This information is intended for the user.</entry> <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. It may -not be valid for any other type of control, including -<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note this is a +bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the +lowest valid index (always 0) 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> @@ -149,16 +152,21 @@ signed value.</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. It may not be valid for any other type of control, including -<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note this is a +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. It may not be -valid for any other type of control, including +<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 @@ -171,7 +179,7 @@ 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 although signed, the step value is supposed to +128.</para><para>Note that although signed, the step value is supposed to be always positive.</para></entry> </row> <row> @@ -188,7 +196,7 @@ func-open; is called.</entry> <entry>__u32</entry> <entry><structfield>flags</structfield></entry> <entry>Control flags, see <xref - linkend="control-flags">.</entry> + linkend="control-flags" />.</entry> </row> <row> <entry>__u32</entry> @@ -237,11 +245,11 @@ the array to zero.</entry> <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*"> + <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> @@ -297,13 +305,27 @@ Drivers must ignore the value passed with 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">), the +equal to a control class code (see <xref linkend="ctrl-class" />), 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> |