leandrof/linux
1
0
Fork 0
forked from Minki/linux
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[media] DocBook media: update VIDIOC_G/S/TRY_EXT_CTRLS

Browse Source 
Document the support for the new compound type controls.

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <m.chehab@samsung.com>
This commit is contained in:
Hans Verkuil 2014-04-04 08:14:55 -03:00 committed by Mauro Carvalho Chehab
parent 715bfb3e1f
commit a4c8c262f8
1 changed files with 29 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
View File

@ -72,23 +72,30 @@ 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>
must also set the <structfield>string</structfield> field. Controls
of compound types (<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set)
must set the <structfield>ptr</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
memory to this new size and try again. For the string type 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>N-dimensional arrays are set and retrieved row-by-row. You cannot set a partial
array, all elements have to be set or retrieved. The total size is calculated
as <structfield>elems</structfield> * <structfield>elem_size</structfield>.
These values can be obtained by calling &VIDIOC-QUERY-EXT-CTRL;.</para>
<para>To change the value of a set of controls applications
initialize the <structfield>id</structfield>, <structfield>size</structfield>,
<structfield>reserved2</structfield> and
<structfield>value/string</structfield> fields of each &v4l2-ext-control; and
<structfield>value/value64/string/ptr</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>
@ -96,7 +103,7 @@ valid.</para>
<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
<structfield>value/value64/string/ptr</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>
@ -158,19 +165,33 @@ applications must set the array to zero.</entry>
<entry></entry>
<entry>__s32</entry>
<entry><structfield>value</structfield></entry>
<entry>New value or current value.</entry>
<entry>New value or current value. Valid if this control is not of
type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry>
</row>
<row>
<entry></entry>
<entry>__s64</entry>
<entry><structfield>value64</structfield></entry>
<entry>New value or current value.</entry>
<entry>New value or current value. Valid if this control is of
type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry>
</row>
<row>
<entry></entry>
<entry>char *</entry>
<entry><structfield>string</structfield></entry>
<entry>A pointer to a string.</entry>
<entry>A pointer to a string. Valid if this control is of
type <constant>V4L2_CTRL_TYPE_STRING</constant>.</entry>
</row>
<row>
<entry></entry>
<entry>void *</entry>
<entry><structfield>ptr</structfield></entry>
<entry>A pointer to a compound type which can be an N-dimensional array and/or a
compound type (the control's type is >= <constant>V4L2_CTRL_COMPOUND_TYPES</constant>).
Valid if <constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set for this control.
</entry>
</row>
</tbody>
</tgroup>