Add documentation for V4L2 subdev selection API. This changes also experimental V4L2 subdev API so that scaling now works through selection API only. Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi> Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>tirimbino
Sakari Ailus
13 years ago
committed by
Mauro Carvalho Chehab
parent
59ef29cc86
commit
955f645aea
@ -0,0 +1,228 @@ |
||||
<refentry id="vidioc-subdev-g-selection"> |
||||
<refmeta> |
||||
<refentrytitle>ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION</refentrytitle> |
||||
&manvol; |
||||
</refmeta> |
||||
|
||||
<refnamediv> |
||||
<refname>VIDIOC_SUBDEV_G_SELECTION</refname> |
||||
<refname>VIDIOC_SUBDEV_S_SELECTION</refname> |
||||
<refpurpose>Get or set selection rectangles on a subdev pad</refpurpose> |
||||
</refnamediv> |
||||
|
||||
<refsynopsisdiv> |
||||
<funcsynopsis> |
||||
<funcprototype> |
||||
<funcdef>int <function>ioctl</function></funcdef> |
||||
<paramdef>int <parameter>fd</parameter></paramdef> |
||||
<paramdef>int <parameter>request</parameter></paramdef> |
||||
<paramdef>struct v4l2_subdev_selection *<parameter>argp</parameter></paramdef> |
||||
</funcprototype> |
||||
</funcsynopsis> |
||||
</refsynopsisdiv> |
||||
|
||||
<refsect1> |
||||
<title>Arguments</title> |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term><parameter>fd</parameter></term> |
||||
<listitem> |
||||
<para>&fd;</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><parameter>request</parameter></term> |
||||
<listitem> |
||||
<para>VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><parameter>argp</parameter></term> |
||||
<listitem> |
||||
<para></para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
</refsect1> |
||||
|
||||
<refsect1> |
||||
<title>Description</title> |
||||
|
||||
<note> |
||||
<title>Experimental</title> |
||||
<para>This is an <link linkend="experimental">experimental</link> |
||||
interface and may change in the future.</para> |
||||
</note> |
||||
|
||||
<para>The selections are used to configure various image |
||||
processing functionality performed by the subdevs which affect the |
||||
image size. This currently includes cropping, scaling and |
||||
composition.</para> |
||||
|
||||
<para>The selection API replaces <link |
||||
linkend="vidioc-subdev-g-crop">the old subdev crop API</link>. All |
||||
the function of the crop API, and more, are supported by the |
||||
selections API.</para> |
||||
|
||||
<para>See <xref linkend="subdev"></xref> for |
||||
more information on how each selection target affects the image |
||||
processing pipeline inside the subdevice.</para> |
||||
|
||||
<section> |
||||
<title>Types of selection targets</title> |
||||
|
||||
<para>There are two types of selection targets: actual and bounds. |
||||
The ACTUAL targets are the targets which configure the hardware. |
||||
The BOUNDS target will return a rectangle that contain all |
||||
possible ACTUAL rectangles.</para> |
||||
</section> |
||||
|
||||
<section> |
||||
<title>Discovering supported features</title> |
||||
|
||||
<para>To discover which targets are supported, the user can |
||||
perform <constant>VIDIOC_SUBDEV_G_SELECTION</constant> on them. |
||||
Any unsupported target will return |
||||
<constant>EINVAL</constant>.</para> |
||||
</section> |
||||
|
||||
<table pgwide="1" frame="none" id="v4l2-subdev-selection-targets"> |
||||
<title>V4L2 subdev selection targets</title> |
||||
<tgroup cols="3"> |
||||
&cs-def; |
||||
<tbody valign="top"> |
||||
<row> |
||||
<entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL</constant></entry> |
||||
<entry>0x0000</entry> |
||||
<entry>Actual crop. Defines the cropping |
||||
performed by the processing step.</entry> |
||||
</row> |
||||
<row> |
||||
<entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_BOUNDS</constant></entry> |
||||
<entry>0x0002</entry> |
||||
<entry>Bounds of the crop rectangle.</entry> |
||||
</row> |
||||
<row> |
||||
<entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL</constant></entry> |
||||
<entry>0x0100</entry> |
||||
<entry>Actual compose rectangle. Used to configure scaling |
||||
on sink pads and composition on source pads.</entry> |
||||
</row> |
||||
<row> |
||||
<entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS</constant></entry> |
||||
<entry>0x0102</entry> |
||||
<entry>Bounds of the compose rectangle.</entry> |
||||
</row> |
||||
</tbody> |
||||
</tgroup> |
||||
</table> |
||||
|
||||
<table pgwide="1" frame="none" id="v4l2-subdev-selection-flags"> |
||||
<title>V4L2 subdev selection flags</title> |
||||
<tgroup cols="3"> |
||||
&cs-def; |
||||
<tbody valign="top"> |
||||
<row> |
||||
<entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant></entry> |
||||
<entry>(1 << 0)</entry> <entry>Suggest the driver it |
||||
should choose greater or equal rectangle (in size) than |
||||
was requested. Albeit the driver may choose a lesser size, |
||||
it will only do so due to hardware limitations. Without |
||||
this flag (and |
||||
<constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant>) the |
||||
behaviour is to choose the closest possible |
||||
rectangle.</entry> |
||||
</row> |
||||
<row> |
||||
<entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant></entry> |
||||
<entry>(1 << 1)</entry> <entry>Suggest the driver it |
||||
should choose lesser or equal rectangle (in size) than was |
||||
requested. Albeit the driver may choose a greater size, it |
||||
will only do so due to hardware limitations.</entry> |
||||
</row> |
||||
<row> |
||||
<entry><constant>V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG</constant></entry> |
||||
<entry>(1 << 2)</entry> |
||||
<entry>The configuration should not be propagated to any |
||||
further processing steps. If this flag is not given, the |
||||
configuration is propagated inside the subdevice to all |
||||
further processing steps.</entry> |
||||
</row> |
||||
</tbody> |
||||
</tgroup> |
||||
</table> |
||||
|
||||
<table pgwide="1" frame="none" id="v4l2-subdev-selection"> |
||||
<title>struct <structname>v4l2_subdev_selection</structname></title> |
||||
<tgroup cols="3"> |
||||
&cs-str; |
||||
<tbody valign="top"> |
||||
<row> |
||||
<entry>__u32</entry> |
||||
<entry><structfield>which</structfield></entry> |
||||
<entry>Active or try selection, from |
||||
&v4l2-subdev-format-whence;.</entry> |
||||
</row> |
||||
<row> |
||||
<entry>__u32</entry> |
||||
<entry><structfield>pad</structfield></entry> |
||||
<entry>Pad number as reported by the media framework.</entry> |
||||
</row> |
||||
<row> |
||||
<entry>__u32</entry> |
||||
<entry><structfield>target</structfield></entry> |
||||
<entry>Target selection rectangle. See |
||||
<xref linkend="v4l2-subdev-selection-targets">.</xref>.</entry> |
||||
</row> |
||||
<row> |
||||
<entry>__u32</entry> |
||||
<entry><structfield>flags</structfield></entry> |
||||
<entry>Flags. See |
||||
<xref linkend="v4l2-subdev-selection-flags">.</xref></entry> |
||||
</row> |
||||
<row> |
||||
<entry>&v4l2-rect;</entry> |
||||
<entry><structfield>rect</structfield></entry> |
||||
<entry>Selection rectangle, in pixels.</entry> |
||||
</row> |
||||
<row> |
||||
<entry>__u32</entry> |
||||
<entry><structfield>reserved</structfield>[8]</entry> |
||||
<entry>Reserved for future extensions. Applications and drivers must |
||||
set the array to zero.</entry> |
||||
</row> |
||||
</tbody> |
||||
</tgroup> |
||||
</table> |
||||
|
||||
</refsect1> |
||||
|
||||
<refsect1> |
||||
&return-value; |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term><errorcode>EBUSY</errorcode></term> |
||||
<listitem> |
||||
<para>The selection rectangle can't be changed because the |
||||
pad is currently busy. This can be caused, for instance, by |
||||
an active video stream on the pad. The ioctl must not be |
||||
retried without performing another action to fix the problem |
||||
first. Only returned by |
||||
<constant>VIDIOC_SUBDEV_S_SELECTION</constant></para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><errorcode>EINVAL</errorcode></term> |
||||
<listitem> |
||||
<para>The &v4l2-subdev-selection; |
||||
<structfield>pad</structfield> references a non-existing |
||||
pad, the <structfield>which</structfield> field references a |
||||
non-existing format, or the selection target is not |
||||
supported on the given subdev pad.</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
</refsect1> |
||||
</refentry> |
||||
Loading…
Reference in new issue