Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 955f645a authored by Sakari Ailus's avatar Sakari Ailus Committed by Mauro Carvalho Chehab
Browse files

[media] v4l: Add subdev selections documentation 



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: default avatarSakari Ailus <sakari.ailus@iki.fi>
Acked-by: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 59ef29cc

Documentation/DocBook/media/Makefile

+3 −1
Original line number Diff line number Diff line
@@ -70,6 +70,8 @@ IOCTLS = \ 
	VIDIOC_SUBDEV_ENUM_MBUS_CODE \

	VIDIOC_SUBDEV_ENUM_FRAME_SIZE \

	VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL \

	VIDIOC_SUBDEV_G_SELECTION \

	VIDIOC_SUBDEV_S_SELECTION \



TYPES = \

	$(shell perl -ne 'print "$$1 " if /^typedef\s+[^\s]+\s+([^\s]+)\;/' $(srctree)/include/linux/videodev2.h) \
@@ -193,7 +195,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 $< >$@

Documentation/DocBook/media/v4l/compat.xml

+9 −0
Original line number Diff line number Diff line
@@ -2417,6 +2417,11 @@ details.</para> 
	  <para>Added integer menus, the new type will be

	  V4L2_CTRL_TYPE_INTEGER_MENU.</para>

        </listitem>

        <listitem>

	  <para>Added selection API for V4L2 subdev interface:

	  &VIDIOC-SUBDEV-G-SELECTION; and

	  &VIDIOC-SUBDEV-S-SELECTION;.</para>

        </listitem>

      </orderedlist>

    </section>
@@ -2533,6 +2538,10 @@ ioctls.</para> 
        <listitem>

	  <para>Selection API. <xref linkend="selection-api" /></para>

        </listitem>

        <listitem>

	  <para>Sub-device selection API: &VIDIOC-SUBDEV-G-SELECTION;

	  and &VIDIOC-SUBDEV-S-SELECTION; ioctls.</para>

        </listitem>

      </itemizedlist>

    </section>

Documentation/DocBook/media/v4l/dev-subdev.xml

+178 −24
Original line number Diff line number Diff line
@@ -76,11 +76,12 @@ 
    <wordasword>format</wordasword> means the combination of media bus data

    format, frame width and frame height.</para></note>



    <para>Image formats are typically negotiated on video capture and output

    devices using the <link linkend="crop">cropping and scaling</link> 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.</para>

    <para>Image formats are typically negotiated on video capture and

    output devices using the format and <link

    linkend="vidioc-subdev-g-selection">selection</link> 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.</para>



    <para>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 @@ 
    </section>



    <section>

      <title>Cropping and scaling</title>

      <title>Selections: cropping, scaling and composition</title>



      <para>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.</para>
@@ -288,26 +289,179 @@ 
      &v4l2-rect; by the coordinates of the top left corner and the rectangle

      size. Both the coordinates and sizes are expressed in pixels.</para>



      <para>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.</para>



      <para>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.</para>



      <para>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.

      </para>

      <para>As for pad formats, drivers store try and active

      rectangles for the selection targets of ACTUAL type <xref

      linkend="v4l2-subdev-selection-targets">.</xref></para>



      <para>On sink pads, cropping is applied relative 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.</para>



      <para>The scaling operation changes the size of the image by

      scaling it to new dimensions. The scaling ratio isn't specified

      explicitly, but is implied from the original and scaled image

      sizes. Both sizes are represented by &v4l2-rect;.</para>



      <para>Scaling support is optional. When supported by a subdev,

      the crop rectangle on the subdev's sink pad is scaled to the

      size configured using the &VIDIOC-SUBDEV-S-SELECTION; IOCTL

      using <constant>V4L2_SUBDEV_SEL_COMPOSE_ACTUAL</constant>

      selection target on the same pad. If the subdev supports scaling

      but not composing, the top and left values are not used and must

      always be set to zero.</para>



      <para>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

      contained inside the source image size for the crop

      operation.</para>



      <para>The drivers should always use the closest possible

      rectangle the user requests on all selection targets, unless

      specifically told otherwise.

      <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant> and

      <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant> flags may be

      used to round the image size either up or down. <xref

      linkend="v4l2-subdev-selection-flags"></xref></para>

    </section>



    <section>

      <title>Types of selection targets</title>



      <section>

	<title>ACTUAL targets</title>



	<para>ACTUAL targets reflect the actual hardware configuration

	at any point of time. There is a BOUNDS target

	corresponding to every ACTUAL.</para>

      </section>



      <para>Cropping behaviour on output pads is not defined.</para>

      <section>

	<title>BOUNDS targets</title>



	<para>BOUNDS targets is the smallest rectangle that contains

	all valid ACTUAL rectangles. It may not be possible to set the

	ACTUAL rectangle as large as the BOUNDS rectangle, however.

	This may be because e.g. a sensor's pixel array is not

	rectangular but cross-shaped or round. The maximum size may

	also be smaller than the BOUNDS rectangle.</para>

      </section>



    </section>



    <section>

      <title>Order of configuration and format propagation</title>



      <para>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. This

      flag causes no propagation of the changes are allowed in any

      circumstances. This may also cause the accessed rectangle to be

      adjusted by the driver, depending on the properties of the

      underlying hardware.</para>



      <para>The coordinates to a step always refer to the actual 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.</para>



      <orderedlist>

	<listitem>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.</listitem>



	<listitem>Sink pad actual crop selection. The sink pad crop

	defines the crop performed to the sink pad format.</listitem>



	<listitem>Sink pad actual 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 actual

	sink compose rectangle in the sink compose bounds

	rectangle.</listitem>



	<listitem>Source pad actual crop selection. Crop on the source

	pad defines crop performed to the image in the sink compose

	bounds rectangle.</listitem>



	<listitem>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

	actual crop selection.</listitem>

      </orderedlist>



      <para>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.</para>



      <figure id="subdev-image-processing-crop">

	<title>Image processing in subdevs: simple crop example</title>

	<mediaobject>

	  <imageobject>

	    <imagedata fileref="subdev-image-processing-crop.svg"

	    format="SVG" scale="200" />

	  </imageobject>

	</mediaobject>

      </figure>



      <para>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 actual 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.</para>



      <figure id="subdev-image-processing-scaling-multi-source">

	<title>Image processing in subdevs: scaling with multiple sources</title>

	<mediaobject>

	  <imageobject>

	    <imagedata fileref="subdev-image-processing-scaling-multi-source.svg"

	    format="SVG" scale="200" />

	  </imageobject>

	</mediaobject>

      </figure>



      <para>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.</para>



      <figure id="subdev-image-processing-full">

	<title>Image processing in subdevs: scaling and composition

	with multiple sinks and sources</title>

	<mediaobject>

	  <imageobject>

	    <imagedata fileref="subdev-image-processing-full.svg"

	    format="SVG" scale="200" />

	  </imageobject>

	</mediaobject>

      </figure>



      <para>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.</para>



    </section>



  </section>



  &sub-subdev-formats;

Documentation/DocBook/media/v4l/v4l2.xml

+14 −1
Original line number Diff line number Diff line
@@ -96,6 +96,17 @@ Remote Controller chapter.</contrib> 
	  </address>

	</affiliation>

      </author>



      <author>

	<firstname>Sakari</firstname>

	<surname>Ailus</surname>

	<contrib>Subdev selections API.</contrib>

	<affiliation>

	  <address>

	    <email>sakari.ailus@iki.fi</email>

	  </address>

	</affiliation>

      </author>

    </authorgroup>



    <copyright>
@@ -131,7 +142,8 @@ applications. --> 
	<revnumber>3.5</revnumber>

	<date>2012-04-02</date>

	<authorinitials>sa</authorinitials>

	<revremark>Added V4L2_CTRL_TYPE_INTEGER_MENU.

	<revremark>Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev

	    selections API.

	</revremark>

      </revision>
@@ -548,6 +560,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;

    <!-- End of ioctls. -->

    &sub-mmap;

Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml

0 → 100644
+228 −0
Original line number Diff line number Diff line 
<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 &lt;&lt; 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 &lt;&lt; 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 &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>

	</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>