diff options
Diffstat (limited to 'v4l2-spec/vidioc-queryctrl.sgml')
| -rw-r--r-- | v4l2-spec/vidioc-queryctrl.sgml | 42 |
1 files changed, 32 insertions, 10 deletions
diff --git a/v4l2-spec/vidioc-queryctrl.sgml b/v4l2-spec/vidioc-queryctrl.sgml index 9908a964d..abf56b22e 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 @@ -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> @@ -297,6 +305,20 @@ 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> |