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

Commit 64b9ce83 authored by Sakari Ailus's avatar Sakari Ailus Committed by Mauro Carvalho Chehab
Browse files

[media] v4l: Common documentation for selection targets 



Both V4L2 and V4L2 subdev interface have very similar selection APIs with
differences foremost related to in-memory and media bus formats. However,
the selection targets are the same for both. Most targets are and in the
future will likely continue to be more the same than with any differences.
Thus it makes sense to unify the documentation of the targets.

Signed-off-by: default avatarSakari Ailus <sakari.ailus@iki.fi>
Acked-by: default avatarSylwester Nawrocki <s.nawrocki@samsung.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 5689b288

Documentation/DocBook/media/v4l/compat.xml

+5 −4
Original line number Diff line number Diff line
@@ -2377,9 +2377,10 @@ that used it. It was originally scheduled for removal in 2.6.35. 
	  <para>V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace.</para>

        </listitem>

        <listitem>

	  <para>Add selection API for extended control over cropping and

composing. Does not affect the compatibility of current drivers and

applications.  See <link linkend="selection-api"> selection API </link> for

	  <para>Add selection API for extended control over cropping

	  and composing. Does not affect the compatibility of current

	  drivers and applications. See <link

	  linkend="selection-api"> selection API </link> for

	  details.</para>

        </listitem>

      </orderedlist>

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

+6 −6
Original line number Diff line number Diff line
@@ -276,7 +276,7 @@ 
      </para>

    </section>



    <section>

    <section id="v4l2-subdev-selections">

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



      <para>Many sub-devices support cropping frames on their input or output
@@ -289,9 +289,9 @@ 
      &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>As for pad formats, drivers store try and active rectangles for

      the selection targets <xref

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

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

      rectangles for the selection targets <xref

      linkend="v4l2-selections-common" />.</para>



      <para>On sink pads, cropping is applied relative to the

      current pad format. The pad format represents the image size as
@@ -308,7 +308,7 @@ 
      <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_TGT_COMPOSE</constant>

      using <constant>V4L2_SEL_TGT_COMPOSE</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>
@@ -362,7 +362,7 @@ 
      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

      <constant>V4L2_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

Documentation/DocBook/media/v4l/selection-api.xml

+3 −3
Original line number Diff line number Diff line
@@ -53,11 +53,11 @@ cropping and composing rectangles have the same size.</para> 
	</mediaobject>

      </figure>



For complete list of the available selection targets see table <xref

linkend="v4l2-sel-target"/>



    </section>



    See <xref linkend="v4l2-selection-targets-table" /> for more

    information.



  <section>



  <title>Configuration</title>

Documentation/DocBook/media/v4l/selections-common.xml

0 → 100644
+92 −0
Original line number Diff line number Diff line 
<section id="v4l2-selections-common">



  <title>Selection targets</title>



  <para>While the <link linkend="selection-api">V4L2 selection

  API</link> and <link linkend="v4l2-subdev-selections">V4L2 subdev

  selection APIs</link> are very similar, there's one fundamental

  difference between the two. On sub-device API, the selection

  rectangle refers to the media bus format, and is bound to a

  sub-device's pad. On the V4L2 interface the selection rectangles

  refer to the in-memory pixel format.</para>



  <para>The precise meaning of the selection targets may thus be

  affected on which of the two interfaces they are used.</para>



  <table pgwide="1" frame="none" id="v4l2-selection-targets-table">

  <title>Selection target definitions</title>

    <tgroup cols="5">

      <colspec colname="c1" />

      <colspec colname="c2" />

      <colspec colname="c3" />

      <colspec colname="c4" />

      <colspec colname="c5" />

      &cs-def;

      <thead>

	<row rowsep="1">

	  <entry align="left">Target name</entry>

	  <entry align="left">id</entry>

	  <entry align="left">Definition</entry>

	  <entry align="left">Valid for V4L2</entry>

	  <entry align="left">Valid for V4L2 subdev</entry>

	</row>

      </thead>

      <tbody valign="top">

	<row>

	  <entry><constant>V4L2_SEL_TGT_CROP</constant></entry>

	  <entry>0x0000</entry>

	  <entry>Crop rectangle. Defines the cropped area.</entry>

	  <entry>Yes</entry>

	  <entry>Yes</entry>

	</row>

	<row>

          <entry><constant>V4L2_SEL_TGT_CROP_DEFAULT</constant></entry>

          <entry>0x0001</entry>

          <entry>Suggested cropping rectangle that covers the "whole picture".</entry>

	  <entry>Yes</entry>

	  <entry>No</entry>

	</row>

	<row>

	  <entry><constant>V4L2_SEL_TGT_CROP_BOUNDS</constant></entry>

	  <entry>0x0002</entry>

	  <entry>Bounds of the crop rectangle. All valid crop

	  rectangles fit inside the crop bounds rectangle.

	  </entry>

	  <entry>Yes</entry>

	  <entry>Yes</entry>

	</row>

	<row>

	  <entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry>

	  <entry>0x0100</entry>

	  <entry>Compose rectangle. Used to configure scaling

	  and composition.</entry>

	  <entry>Yes</entry>

	  <entry>Yes</entry>

	</row>

	<row>

          <entry><constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant></entry>

          <entry>0x0101</entry>

          <entry>Suggested composition rectangle that covers the "whole picture".</entry>

	  <entry>Yes</entry>

	  <entry>No</entry>

	</row>

	<row>

	  <entry><constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant></entry>

	  <entry>0x0102</entry>

	  <entry>Bounds of the compose rectangle. All valid compose

	  rectangles fit inside the compose bounds rectangle.</entry>

	  <entry>Yes</entry>

	  <entry>Yes</entry>

	</row>

	<row>

          <entry><constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant></entry>

          <entry>0x0103</entry>

          <entry>The active area and all padding pixels that are inserted or

	    modified by hardware.</entry>

	  <entry>Yes</entry>

	  <entry>No</entry>

	</row>

      </tbody>

    </tgroup>

  </table>

</section>

Documentation/DocBook/media/v4l/v4l2.xml

+5 −0
Original line number Diff line number Diff line
@@ -589,6 +589,11 @@ and discussions on the V4L mailing list.</revremark> 
    &sub-write;

  </appendix>



  <appendix>

    <title>Common definitions for V4L2 and V4L2 subdev interfaces</title>

      &sub-selections-common;

  </appendix>



  <appendix id="videodev">

    <title>Video For Linux Two Header File</title>

    &sub-videodev2-h;