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

Commit f6a5cb1b authored by Antti Koskipaa's avatar Antti Koskipaa Committed by Mauro Carvalho Chehab
Browse files

[media] v4l: v4l2_subdev userspace crop API 



This patch adds the VIDIOC_SUBDEV_S_CROP and G_CROP ioctls to the
userland API. CROPCAP is not implemented because it's redundant.

Signed-off-by: default avatarAntti Koskipaa <akoskipa@gmail.com>
Signed-off-by: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: default avatarHans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 35c3017a

Documentation/DocBook/media-entities.tmpl

+4 −0
Original line number Diff line number Diff line
@@ -88,8 +88,10 @@ 
<!ENTITY VIDIOC-S-TUNER "<link linkend='vidioc-g-tuner'><constant>VIDIOC_S_TUNER</constant></link>">

<!ENTITY VIDIOC-SUBDEV-ENUM-FRAME-SIZE "<link linkend='vidioc-subdev-enum-frame-size'><constant>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</constant></link>">

<!ENTITY VIDIOC-SUBDEV-ENUM-MBUS-CODE "<link linkend='vidioc-subdev-enum-mbus-code'><constant>VIDIOC_SUBDEV_ENUM_MBUS_CODE</constant></link>">

<!ENTITY VIDIOC-SUBDEV-G-CROP "<link linkend='vidioc-subdev-g-crop'><constant>VIDIOC_SUBDEV_G_CROP</constant></link>">

<!ENTITY VIDIOC-SUBDEV-G-FMT "<link linkend='vidioc-subdev-g-fmt'><constant>VIDIOC_SUBDEV_G_FMT</constant></link>">

<!ENTITY VIDIOC-SUBDEV-G-FRAME-INTERVAL "<link linkend='vidioc-subdev-g-frame-interval'><constant>VIDIOC_SUBDEV_G_FRAME_INTERVAL</constant></link>">

<!ENTITY VIDIOC-SUBDEV-S-CROP "<link linkend='vidioc-subdev-g-crop'><constant>VIDIOC_SUBDEV_S_CROP</constant></link>">

<!ENTITY VIDIOC-SUBDEV-S-FMT "<link linkend='vidioc-subdev-g-fmt'><constant>VIDIOC_SUBDEV_S_FMT</constant></link>">

<!ENTITY VIDIOC-SUBDEV-S-FRAME-INTERVAL "<link linkend='vidioc-subdev-g-frame-interval'><constant>VIDIOC_SUBDEV_S_FRAME_INTERVAL</constant></link>">

<!ENTITY VIDIOC-TRY-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_TRY_ENCODER_CMD</constant></link>">
@@ -198,6 +200,7 @@ 
<!ENTITY v4l2-subdev-frame-interval "struct&nbsp;<link linkend='v4l2-subdev-frame-interval'>v4l2_subdev_frame_interval</link>">

<!ENTITY v4l2-subdev-frame-interval-enum "struct&nbsp;<link linkend='v4l2-subdev-frame-interval-enum'>v4l2_subdev_frame_interval_enum</link>">

<!ENTITY v4l2-subdev-frame-size-enum "struct&nbsp;<link linkend='v4l2-subdev-frame-size-enum'>v4l2_subdev_frame_size_enum</link>">

<!ENTITY v4l2-subdev-crop "struct&nbsp;<link linkend='v4l2-subdev-crop'>v4l2_subdev_crop</link>">

<!ENTITY v4l2-subdev-format "struct&nbsp;<link linkend='v4l2-subdev-format'>v4l2_subdev_format</link>">

<!ENTITY v4l2-subdev-mbus-code-enum "struct&nbsp;<link linkend='v4l2-subdev-mbus-code-enum'>v4l2_subdev_mbus_code_enum</link>">

<!ENTITY v4l2-standard "struct&nbsp;<link linkend='v4l2-standard'>v4l2_standard</link>">
@@ -339,6 +342,7 @@ 
<!ENTITY sub-subdev-enum-frame-size SYSTEM "v4l/vidioc-subdev-enum-frame-size.xml">

<!ENTITY sub-subdev-enum-mbus-code SYSTEM "v4l/vidioc-subdev-enum-mbus-code.xml">

<!ENTITY sub-subdev-formats SYSTEM "v4l/subdev-formats.xml">

<!ENTITY sub-subdev-g-crop SYSTEM "v4l/vidioc-subdev-g-crop.xml">

<!ENTITY sub-subdev-g-fmt SYSTEM "v4l/vidioc-subdev-g-fmt.xml">

<!ENTITY sub-subdev-g-frame-interval SYSTEM "v4l/vidioc-subdev-g-frame-interval.xml">

<!ENTITY sub-capture-c SYSTEM "v4l/capture.c.xml">

Documentation/DocBook/v4l/dev-subdev.xml

+33 −0
Original line number Diff line number Diff line
@@ -275,6 +275,39 @@ 
      </para>

    </section>



    <section>

      <title>Cropping and scaling</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

      also be used as part of digital zoom implementations to select the area of

      the image that will be scaled up.</para>



      <para>Crop settings are defined by a crop rectangle and represented in a

      &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>Cropping behaviour on output pads is not defined.</para>



    </section>

  </section>



  &sub-subdev-formats;

Documentation/DocBook/v4l/v4l2.xml

+1 −0
Original line number Diff line number Diff line
@@ -510,6 +510,7 @@ and discussions on the V4L mailing list.</revremark> 
    &sub-subdev-enum-frame-interval;

    &sub-subdev-enum-frame-size;

    &sub-subdev-enum-mbus-code;

    &sub-subdev-g-crop;

    &sub-subdev-g-fmt;

    &sub-subdev-g-frame-interval;

    &sub-subscribe-event;

Documentation/DocBook/v4l/vidioc-subdev-g-crop.xml

0 → 100644
+155 −0
Original line number Diff line number Diff line 
<refentry id="vidioc-subdev-g-crop">

  <refmeta>

    <refentrytitle>ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP</refentrytitle>

    &manvol;

  </refmeta>



  <refnamediv>

    <refname>VIDIOC_SUBDEV_G_CROP</refname>

    <refname>VIDIOC_SUBDEV_S_CROP</refname>

    <refpurpose>Get or set the crop rectangle 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_crop *<parameter>argp</parameter></paramdef>

      </funcprototype>

    </funcsynopsis>

    <funcsynopsis>

      <funcprototype>

	<funcdef>int <function>ioctl</function></funcdef>

	<paramdef>int <parameter>fd</parameter></paramdef>

	<paramdef>int <parameter>request</parameter></paramdef>

	<paramdef>const struct v4l2_subdev_crop *<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_CROP, VIDIOC_SUBDEV_S_CROP</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>To retrieve the current crop rectangle applications set the

    <structfield>pad</structfield> field of a &v4l2-subdev-crop; to the

    desired pad number as reported by the media API and the

    <structfield>which</structfield> field to

    <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. They then call the

    <constant>VIDIOC_SUBDEV_G_CROP</constant> ioctl with a pointer to this

    structure. The driver fills the members of the <structfield>rect</structfield>

    field or returns &EINVAL; if the input arguments are invalid, or if cropping

    is not supported on the given pad.</para>



    <para>To change the current crop rectangle applications set both the

    <structfield>pad</structfield> and <structfield>which</structfield> fields

    and all members of the <structfield>rect</structfield> field. They then call

    the <constant>VIDIOC_SUBDEV_S_CROP</constant> ioctl with a pointer to this

    structure. The driver verifies the requested crop rectangle, adjusts it

    based on the hardware capabilities and configures the device. Upon return

    the &v4l2-subdev-crop; contains the current format as would be returned

    by a <constant>VIDIOC_SUBDEV_G_CROP</constant> call.</para>



    <para>Applications can query the device capabilities by setting the

    <structfield>which</structfield> to

    <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. When set, 'try' crop

    rectangles are not applied to the device by the driver, but are mangled

    exactly as active crop rectangles and stored in the sub-device file handle.

    Two applications querying the same sub-device would thus not interact with

    each other.</para>



    <para>Drivers must not return an error solely because the requested crop

    rectangle doesn't match the device capabilities. They must instead modify

    the rectangle to match what the hardware can provide. The modified format

    should be as close as possible to the original request.</para>



    <table pgwide="1" frame="none" id="v4l2-subdev-crop">

      <title>struct <structname>v4l2_subdev_crop</structname></title>

      <tgroup cols="3">

        &cs-str;

	<tbody valign="top">

	  <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>which</structfield></entry>

	    <entry>Crop rectangle to get or set, from

	    &v4l2-subdev-format-whence;.</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>

	</tbody>

      </tgroup>

    </table>

  </refsect1>



  <refsect1>

    &return-value;



    <variablelist>

      <varlistentry>

	<term><errorcode>EBUSY</errorcode></term>

	<listitem>

	  <para>The crop 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_CROP</constant></para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><errorcode>EINVAL</errorcode></term>

	<listitem>

	  <para>The &v4l2-subdev-crop; <structfield>pad</structfield>

	  references a non-existing pad, the <structfield>which</structfield>

	  field references a non-existing format, or cropping is not supported

	  on the given subdev pad.</para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

</refentry>

drivers/media/video/v4l2-subdev.c

+26 −0
Original line number Diff line number Diff line
@@ -213,6 +213,32 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg) 
		return v4l2_subdev_call(sd, pad, set_fmt, subdev_fh, format);

	}



	case VIDIOC_SUBDEV_G_CROP: {

		struct v4l2_subdev_crop *crop = arg;



		if (crop->which != V4L2_SUBDEV_FORMAT_TRY &&

		    crop->which != V4L2_SUBDEV_FORMAT_ACTIVE)

			return -EINVAL;



		if (crop->pad >= sd->entity.num_pads)

			return -EINVAL;



		return v4l2_subdev_call(sd, pad, get_crop, subdev_fh, crop);

	}



	case VIDIOC_SUBDEV_S_CROP: {

		struct v4l2_subdev_crop *crop = arg;



		if (crop->which != V4L2_SUBDEV_FORMAT_TRY &&

		    crop->which != V4L2_SUBDEV_FORMAT_ACTIVE)

			return -EINVAL;



		if (crop->pad >= sd->entity.num_pads)

			return -EINVAL;



		return v4l2_subdev_call(sd, pad, set_crop, subdev_fh, crop);

	}



	case VIDIOC_SUBDEV_ENUM_MBUS_CODE: {

		struct v4l2_subdev_mbus_code_enum *code = arg;