[PATCH v3 09/33] v4l: Add subdev selections documentation

Sakari Ailus
2012-02-20T01:58:22Z

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>
---
Documentation/DocBook/media/Makefile | 2 +-
Documentation/DocBook/media/v4l/compat.xml | 3 +
Documentation/DocBook/media/v4l/dev-subdev.xml | 188 +++++++++++++++--
Documentation/DocBook/media/v4l/v4l2.xml | 17 ++-
.../media/v4l/vidioc-subdev-g-selection.xml | 222 ++++++++++++++++++++
5 files changed, 405 insertions(+), 27 deletions(-)
create mode 100644 Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml

diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile
index 6628b4b..729f840 100644
--- a/Documentation/DocBook/media/Makefile
+++ b/Documentation/DocBook/media/Makefile
@@ -193,7 +193,7 @@ DVB_DOCUMENTED = \
#

install_media_images = \
- $(Q)cp $(OBJIMGFILES) $(MEDIA_OBJ_DIR)/media_api
+ $(Q)cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api

$(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64
$(Q)base64 -d $< >$@
diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
index 8cd5c96..0c498db 100644
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2407,6 +2407,9 @@ details.
Added integer menus, the new type will be
V4L2_CTRL_TYPE_INTEGER_MENU.

+
+ Added selection API for V4L2 subdev interface.
+



diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml
index 0916a73..9d5e7da 100644
--- a/Documentation/DocBook/media/v4l/dev-subdev.xml
+++ b/Documentation/DocBook/media/v4l/dev-subdev.xml
@@ -76,11 +76,12 @@
<wordasword>format</wordasword> means the combination of media bus data
format, frame width and frame height. </note>

- Image formats are typically negotiated on video capture and output
- devices using the cropping and scaling ioctls.
- The driver is responsible for configuring every block in the video pipeline
- according to the requested format at the pipeline input and/or
- output.
+ Image formats are typically negotiated on video capture and
+ output devices using the format and <link
+ linkend="vidioc-subdev-g-selection">selection ioctls. The
+ driver is responsible for configuring every block in the video
+ pipeline according to the requested format at the pipeline input
+ and/or output.

For complex devices, such as often found in embedded systems,
identical image sizes at the output of a pipeline can be achieved using
@@ -276,11 +277,11 @@



- Cropping and scaling
+ Selections: cropping, scaling and composition

Many sub-devices support cropping frames on their input or output
pads (or possible even on both). Cropping is used to select the area of
- interest in an image, typically on a video sensor or video decoder. It can
+ interest in an image, typically on an image sensor or a video decoder. It can
also be used as part of digital zoom implementations to select the area of
the image that will be scaled up.

@@ -288,26 +289,165 @@
&v4l2-rect; by the coordinates of the top left corner and the rectangle
size. Both the coordinates and sizes are expressed in pixels.

- The crop rectangle is retrieved and set using the
- &VIDIOC-SUBDEV-G-CROP; and &VIDIOC-SUBDEV-S-CROP; ioctls. Like for pad
- formats, drivers store try and active crop rectangles. The format
- negotiation mechanism applies to crop settings as well.
-
- On input pads, cropping is applied relatively to the current pad
- format. The pad format represents the image size as received by the
- sub-device from the previous block in the pipeline, and the crop rectangle
- represents the sub-image that will be transmitted further inside the
- sub-device for processing. The crop rectangle be entirely containted
- inside the input image size.
-
- Input crop rectangle are reset to their default value when the input
- image format is modified. Drivers should use the input image size as the
- crop rectangle default value, but hardware requirements may prevent this.
-
+ Scaling operation changes the size of the image by scaling
+ it to new dimensions. Some sub-devices support it. The scaled
+ size (width and height) is represented by &v4l2-rect;. In the
+ case of scaling, top and left will always be zero. Scaling is
+ configured using &sub-subdev-g-selection; and
+ <constant>V4L2_SUBDEV_SEL_COMPOSE_ACTIVE</constant> selection
+ target on the sink pad of the subdev. The scaling is performed
+ related to the width and height of the crop rectangle on the
+ subdev's sink pad.
+
+ As for pad formats, drivers store try and active
+ rectangles for the selection targets of ACTIVE type <xref
+ linkend="v4l2-subdev-selection-targets">.
+
+ On sink pads, cropping is applied relatively to the
+ current pad format. The pad format represents the image size as
+ received by the sub-device from the previous block in the
+ pipeline, and the crop rectangle represents the sub-image that
+ will be transmitted further inside the sub-device for
+ processing.
+
+ On source pads, cropping is similar to sink pads, with the
+ exception that the source size from which the cropping is
+ performed, is the COMPOSE rectangle on the sink pad. In both
+ sink and source pads, the crop rectangle must be entirely
+ containted inside the source image size for the crop
+ operation.
+
+ The drivers should always use the closest possible
+ rectangle the user requests on all selection targets, unless
+ specificly told otherwise<xref
+ linkend="v4l2-subdev-selection-flags">.
+
+
+
+ Types of selection targets
+
+
+ ACTIVE targets
+
+ ACTIVE targets reflect the actual hardware configuration
+ at any point of time.
+
+
+
+ BOUNDS targets
+
+ BOUNDS targets is the smallest rectangle within which
+ contains all valid ACTIVE rectangles. It may not be possible
+ to set the ACTIVE rectangle as large as the BOUNDS rectangle,
+ however.
+

- Cropping behaviour on output pads is not defined.
+
+
+
+ Order of configuration and format propagation
+
+ Inside subdevs, the order of image processing steps will
+ always be from the sink pad towards the source pad. This is also
+ reflected in the order in which the configuration must be
+ performed by the user: the changes made will be propagated to
+ any subsequent stages. If this behaviour is not desired, the
+ user must set
+ <constant>V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG</constant> flag. The
+ coordinates to a step always refer to the active size of the
+ previous step. The exception to this rule is the source compose
+ rectangle, which refers to the sink compose bounds rectangle ---
+ if it is supported by the hardware.
+
+
+ Sink pad format. The user configures the sink pad
+ format. This format defines the parameters of the image the
+ entity receives through the pad for further processing.
+
+ Sink pad active crop selection. The sink pad crop
+ defines the performed to the sink pad format.
+
+ Sink pad active compose selection. The size of the
+ sink pad compose rectangle defines the scaling ratio compared
+ to the size of the sink pad crop rectangle. The location of
+ the compose rectangle specifies the location of the active
+ sink compose rectangle in the sink compose bounds
+ rectangle.
+
+ Source pad active crop selection. Crop on the source
+ pad defines crop performed to the image in the sink compose
+ bounds rectangle.
+
+ Source pad format. The source pad format defines the
+ output pixel format of the subdev, as well as the other
+ parameters with the exception of the image width and height.
+ Width and height are defined by the size of the source pad
+ active crop selection.
+
+
+ Accessing any of the above rectangles not supported by the
+ subdev will return <constant>EINVAL</constant>. Any rectangle
+ referring to a previous unsupported rectangle coordinates will
+ instead refer to the previous supported rectangle. For example,
+ if sink crop is not supported, the compose selection will refer
+ to the sink pad format dimensions instead.
+
+
+ Image processing in subdevs: simple crop example
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="subdev-image-processing-crop.svg"
+ format="SVG" scale="200" />
+ </imageobject>
+ </mediaobject>
+
+
+ In the above example, the subdev supports cropping on its
+ sink pad. To configure it, the user sets the media bus format on
+ the subdev's sink pad. Now the active crop rectangle can be set
+ on the sink pad --- the location and size of this rectangle
+ reflect the location and size of a rectangle to be cropped from
+ the sink format. The size of the sink crop rectangle will also
+ be the size of the format of the subdev's source pad.
+
+
+ Image processing in subdevs: scaling with multiple sources
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="subdev-image-processing-scaling-multi-source.svg"
+ format="SVG" scale="200" />
+ </imageobject>
+ </mediaobject>
+
+
+ In this example, the subdev is capable of first cropping,
+ then scaling and finally cropping for two source pads
+ individually from the resulting scaled image. The location of
+ the scaled image in the cropped image is ignored in sink compose
+ target. Both of the locations of the source crop rectangles
+ refer to the sink scaling rectangle, independently cropping an
+ area at location specified by the source crop rectangle from
+ it.
+
+
+ Image processing in subdevs: scaling and composition
+ with multiple sinks and sources
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="subdev-image-processing-full.svg"
+ format="SVG" scale="200" />
+ </imageobject>
+ </mediaobject>
+
+
+ The subdev driver supports two sink pads and two source
+ pads. The images from both of the sink pads are individually
+ cropped, then scaled and further composed on the composition
+ bounds rectangle. From that, two independent streams are cropped
+ and sent out of the subdev from the source pads.


+


&sub-subdev-formats;
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index ff11a13..912ec9c 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -96,6 +96,17 @@ Remote Controller chapter.</contrib>

</affiliation>
</author>
+
+ <author>
+ <firstname>Sakari</firstname>
+ <surname>Ailus</surname>
+ <contrib>Subdev selections API.</contrib>
+ <affiliation>
+
+ <email>sakari.ailus@iki.fi</email>
+
+ </affiliation>
+ </author>
</authorgroup>

<copyright>
@@ -129,9 +140,10 @@ applications. -->

<revision>
<revnumber>3.4</revnumber>
- <date>2012-01-26</date>
+ <date>2012-02-02</date>
<authorinitials>sa</authorinitials>
- <revremark>Added V4L2_CTRL_TYPE_INTEGER_MENU.</revremark>
+ <revremark>Added V4L2_CTRL_TYPE_INTEGER_MENU. Added V4L2 subdev
+ selections API.</revremark>
</revision>
<revision>
<revnumber>3.3</revnumber>
@@ -537,6 +549,7 @@ and discussions on the V4L mailing list.</revremark>
&sub-subdev-g-crop;
&sub-subdev-g-fmt;
&sub-subdev-g-frame-interval;
+ &sub-subdev-g-selection;
&sub-subscribe-event;

&sub-mmap;
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
new file mode 100644
index 0000000..033077a
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
@@ -0,0 +1,222 @@
+<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>
+ Arguments
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>fd</parameter></term>
+
+ &fd;
+
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>request</parameter></term>
+
+ VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
+
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>argp</parameter></term>
+
+
+
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ Description
+
+ <note>
+ Experimental
+ This is an experimental
+ interface and may change in the future.
+ </note>
+
+ 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.
+
+ The selection API replaces <link
+ linkend="vidioc-subdev-g-crop">the old subdev crop API . All
+ the function of the crop API, and more, are supported by the
+ selections API.
+
+ See for
+ more information on how each selection target affects the image
+ processing pipeline inside the subdevice.
+
+
+ Types of selection targets
+
+ The are four types of selection targets: active, default,
+ bounds and padding. The ACTIVE targets are the targets which
+ configure the hardware. The BOUNDS target will return the
+ maximum width and height of the target.
+
+
+
+ Discovering supported features
+
+ 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>.
+
+
+
+ V4L2 subdev selection targets
+ <tgroup cols="3">
+ &cs-def;
+
+ <row>
+ <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_ACTIVE</constant></entry>
+ <entry>0x0000</entry>
+ <entry>Active 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_ACTIVE</constant></entry>
+ <entry>0x0100</entry>
+ <entry>Active 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>
+
+ </tgroup>
+
+
+
+ V4L2 subdev selection flags
+ <tgroup cols="3">
+ &cs-def;
+
+ <row>
+ <entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant></entry>
+ <entry>(1 &lt;&lt; 0)</entry>
+ <entry>Suggest the driver it should choose greater or
+ equal rectangle (in size) than was requested.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant></entry>
+ <entry>(1 &lt;&lt; 1)</entry>
+ <entry>Suggest the driver it should choose lesser or
+ equal rectangle (in size) than was requested.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG</constant></entry>
+ <entry>(1 &lt;&lt; 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>
+
+ </tgroup>
+
+
+
+ struct <structname>v4l2_subdev_selection</structname>
+ <tgroup cols="3">
+ &cs-str;
+
+ <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
+ . .</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>flags</structfield></entry>
+ <entry>Flags. See
+ . </entry>
+ </row>
+ <row>
+ <entry>&v4l2-rect;</entry>
+ <entry><structfield>rect</structfield></entry>
+ <entry>Crop rectangle boundaries, 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>
+
+ </tgroup>
+
+
+ </refsect1>
+
+ <refsect1>
+ &return-value;
+
+ <variablelist>
+ <varlistentry>
+ <term><errorcode>EBUSY</errorcode></term>
+
+ 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>
+
+ </varlistentry>
+ <varlistentry>
+ <term><errorcode>EINVAL</errorcode></term>
+
+ 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.
+
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+</refentry>
--
1.7.2.5