diff options
Diffstat (limited to 'v4l2-spec/vidioc-g-ext-ctrls.sgml')
| -rw-r--r-- | v4l2-spec/vidioc-g-ext-ctrls.sgml | 87 |
1 files changed, 70 insertions, 17 deletions
diff --git a/v4l2-spec/vidioc-g-ext-ctrls.sgml b/v4l2-spec/vidioc-g-ext-ctrls.sgml index 510520254..3aa7f8f9f 100644 --- a/v4l2-spec/vidioc-g-ext-ctrls.sgml +++ b/v4l2-spec/vidioc-g-ext-ctrls.sgml @@ -56,7 +56,7 @@ VIDIOC_TRY_EXT_CTRLS</para> <para>These ioctls allow the caller to get or set multiple controls atomically. Control IDs are grouped into control classes (see -<xref linkend="ctrl-class">) and all controls in the control array +<xref linkend="ctrl-class" />) and all controls in the control array must belong to the same control class.</para> <para>Applications must always fill in the @@ -68,20 +68,35 @@ initialize the &v4l2-ext-control; array pointed to by the <structfield>controls</structfield> fields.</para> <para>To get the current value of a set of controls applications -initialize the <structfield>id</structfield> field of each -&v4l2-ext-control; and call the -<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl.</para> +initialize the <structfield>id</structfield>, +<structfield>size</structfield> and <structfield>reserved2</structfield> fields +of each &v4l2-ext-control; and call the +<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls +must also set the <structfield>string</structfield> field.</para> + + <para>If the <structfield>size</structfield> is too small to +receive the control result (only relevant for pointer-type controls +like strings), then the driver will set <structfield>size</structfield> +to a valid value and return an &ENOSPC;. You should re-allocate the +string memory to this new size and try again. It is possible that the +same issue occurs again if the string has grown in the meantime. It is +recommended to call &VIDIOC-QUERYCTRL; first and use +<structfield>maximum</structfield>+1 as the new <structfield>size</structfield> +value. It is guaranteed that that is sufficient memory. +</para> <para>To change the value of a set of controls applications -initialize the <structfield>id</structfield> and -<structfield>value</structfield> fields of a &v4l2-ext-control; and +initialize the <structfield>id</structfield>, <structfield>size</structfield>, +<structfield>reserved2</structfield> and +<structfield>value/string</structfield> fields of each &v4l2-ext-control; and call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls will only be set if <emphasis>all</emphasis> control values are valid.</para> - <para>To check if the a set of controls have correct values -applications initialize the <structfield>id</structfield> and -<structfield>value</structfield> fields of a &v4l2-ext-control; and + <para>To check if a set of controls have correct values applications +initialize the <structfield>id</structfield>, <structfield>size</structfield>, +<structfield>reserved2</structfield> and +<structfield>value/string</structfield> fields of each &v4l2-ext-control; and call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to the driver whether wrong values are automatically adjusted to a valid value or if an error is returned.</para> @@ -112,7 +127,23 @@ application.</entry> </row> <row> <entry>__u32</entry> - <entry><structfield>reserved2</structfield>[2]</entry> + <entry><structfield>size</structfield></entry> + <entry></entry> + <entry>The total size in bytes of the payload of this +control. This is normally 0, but for pointer controls this should be +set to the size of the memory containing the payload, or that will +receive the payload. If <constant>VIDIOC_G_EXT_CTRLS</constant> finds +that this value is less than is required to store +the payload result, then it is set to a value large enough to store the +payload result and ENOSPC is returned. Note that for string controls +this <structfield>size</structfield> field should not be confused with the length of the string. +This field refers to the size of the memory that contains the string. +The actual <emphasis>length</emphasis> of the string may well be much smaller. +</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved2</structfield>[1]</entry> <entry></entry> <entry>Reserved for future extensions. Drivers and applications must set the array to zero.</entry> @@ -135,9 +166,9 @@ applications must set the array to zero.</entry> </row> <row> <entry></entry> - <entry>void *</entry> - <entry><structfield>reserved</structfield></entry> - <entry>Reserved for future pointer-type controls. Currently unused.</entry> + <entry>char *</entry> + <entry><structfield>string</structfield></entry> + <entry>A pointer to a string.</entry> </row> </tbody> </tgroup> @@ -152,7 +183,7 @@ applications must set the array to zero.</entry> <entry>__u32</entry> <entry><structfield>ctrl_class</structfield></entry> <entry>The control class to which all controls belong, see -<xref linkend="ctrl-class">.</entry> +<xref linkend="ctrl-class" />.</entry> </row> <row> <entry>__u32</entry> @@ -194,7 +225,7 @@ if <structfield>count</structfield> equals zero.</entry> <entry><constant>V4L2_CTRL_CLASS_USER</constant></entry> <entry>0x980000</entry> <entry>The class containing user controls. These controls -are described in <xref linkend="control">. All controls that can be set +are described in <xref linkend="control" />. All controls that can be set using the &VIDIOC-S-CTRL; and &VIDIOC-G-CTRL; ioctl belong to this class.</entry> </row> @@ -202,8 +233,22 @@ class.</entry> <entry><constant>V4L2_CTRL_CLASS_MPEG</constant></entry> <entry>0x990000</entry> <entry>The class containing MPEG compression controls. -These controls are described in section <xref - linkend="mpeg-controls">.</entry> +These controls are described in <xref + linkend="mpeg-controls" />.</entry> + </row> + <row> + <entry><constant>V4L2_CTRL_CLASS_CAMERA</constant></entry> + <entry>0x9a0000</entry> + <entry>The class containing camera controls. +These controls are described in <xref + linkend="camera-controls" />.</entry> + </row> + <row> + <entry><constant>V4L2_CTRL_CLASS_FM_TX</constant></entry> + <entry>0x9b0000</entry> + <entry>The class containing FM Transmitter (FM TX) controls. +These controls are described in <xref + linkend="fm-tx-controls" />.</entry> </row> </tbody> </tgroup> @@ -241,6 +286,14 @@ because another applications took over control of the device function this control belongs to.</para> </listitem> </varlistentry> + <varlistentry> + <term><errorcode>ENOSPC</errorcode></term> + <listitem> + <para>The space reserved for the control's payload is insufficient. +The field <structfield>size</structfield> is set to a value that is enough +to store the payload and this error code is returned.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> </refentry> |