Skip to content

Commit

Permalink
[media] v4l: v4l2_subdev userspace crop API
Browse files Browse the repository at this point in the history 
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: Antti Koskipaa <akoskipa@gmail.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: Hans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
  • Loading branch information
Antti Koskipaa authored and Mauro Carvalho Chehab committed Mar 22, 2011
1 parent 35c3017 commit f6a5cb1
Show file tree
Hide file tree
Showing 7 changed files with 238 additions and 0 deletions.
4 changes: 4 additions & 0 deletions Documentation/DocBook/media-entities.tmpl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>">
Expand Down Expand Up @@ -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>">
Expand Down Expand Up @@ -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">
Expand Down
33 changes: 33 additions & 0 deletions Documentation/DocBook/v4l/dev-subdev.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
1 change: 1 addition & 0 deletions Documentation/DocBook/v4l/v4l2.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
155 changes: 155 additions & 0 deletions Documentation/DocBook/v4l/vidioc-subdev-g-crop.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
<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>
26 changes: 26 additions & 0 deletions drivers/media/video/v4l2-subdev.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
15 changes: 15 additions & 0 deletions include/linux/v4l2-subdev.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,19 @@ struct v4l2_subdev_format {
__u32 reserved[8];
};

/**
* struct v4l2_subdev_crop - Pad-level crop settings
* @which: format type (from enum v4l2_subdev_format_whence)
* @pad: pad number, as reported by the media API
* @rect: pad crop rectangle boundaries
*/
struct v4l2_subdev_crop {
__u32 which;
__u32 pad;
struct v4l2_rect rect;
__u32 reserved[8];
};

/**
* struct v4l2_subdev_mbus_code_enum - Media bus format enumeration
* @pad: pad number, as reported by the media API
Expand Down Expand Up @@ -122,5 +135,7 @@ struct v4l2_subdev_frame_interval_enum {
_IOWR('V', 74, struct v4l2_subdev_frame_size_enum)
#define VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL \
_IOWR('V', 75, struct v4l2_subdev_frame_interval_enum)
#define VIDIOC_SUBDEV_G_CROP _IOWR('V', 59, struct v4l2_subdev_crop)
#define VIDIOC_SUBDEV_S_CROP _IOWR('V', 60, struct v4l2_subdev_crop)

#endif
4 changes: 4 additions & 0 deletions include/media/v4l2-subdev.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -431,6 +431,10 @@ struct v4l2_subdev_pad_ops {
struct v4l2_subdev_format *format);
int (*set_fmt)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
struct v4l2_subdev_format *format);
int (*set_crop)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
struct v4l2_subdev_crop *crop);
int (*get_crop)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
struct v4l2_subdev_crop *crop);
};

struct v4l2_subdev_ops {
Expand Down

0 comments on commit f6a5cb1

Please sign in to comment.