diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l/vidioc-queryctrl.xml')
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-queryctrl.xml | 234 |
1 files changed, 197 insertions, 37 deletions
diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml index e6645b99655..2bd98fd7a4e 100644 --- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml +++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml @@ -1,11 +1,12 @@ <refentry id="vidioc-queryctrl"> <refmeta> - <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</refentrytitle> + <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> @@ -24,6 +25,14 @@ <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> @@ -42,7 +51,7 @@ <varlistentry> <term><parameter>request</parameter></term> <listitem> - <para>VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</para> + <para>VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</para> </listitem> </varlistentry> <varlistentry> @@ -67,7 +76,7 @@ structure. The driver fills the rest of the structure or returns an <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 +<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 @@ -89,9 +98,23 @@ 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> +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 @@ -142,38 +165,23 @@ 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 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> +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 <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_BITMASK</constant> controls it is the -set of usable bits. -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> +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 -<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 + <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 @@ -192,10 +200,11 @@ be always positive.</para></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> +<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> @@ -213,6 +222,126 @@ the array to zero.</entry> </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"> @@ -347,11 +476,14 @@ Drivers must ignore the value passed with </row> <row> <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry> - <entry>n/a</entry> - <entry>n/a</entry> - <entry>n/a</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.</entry> +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> @@ -379,6 +511,26 @@ 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> @@ -450,6 +602,14 @@ is in auto-gain mode. In such a case the hardware calculates the gain value base the lighting conditions which can change over time. Note that setting a new value for a volatile control will have no effect. 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> </tbody> </tgroup> </table> |