From: Sakari Ailus <sakari.ailus@linux.intel.com>
To: linux-media@vger.kernel.org
Cc: laurent.pinchart@ideasonboard.com, hverkuil@xs4all.nl,
mchehab@osg.samsung.com,
Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Subject: [RFC v2 18/21] DocBook: media: Document the subdev selection API
Date: Tue, 24 May 2016 19:47:28 +0300 [thread overview]
Message-ID: <1464108451-28142-19-git-send-email-sakari.ailus@linux.intel.com> (raw)
In-Reply-To: <1464108451-28142-1-git-send-email-sakari.ailus@linux.intel.com>
From: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Now that the subdev crop API is considered obsolete, the selection API
that replaces it deserves a full documentation instead of referring to
the crop API documentation.
Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
---
.../media/v4l/vidioc-subdev-g-selection.xml | 37 ++++++++++++++++++++++
1 file changed, 37 insertions(+)
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
index 8346b2e..faac955 100644
--- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
@@ -63,6 +63,43 @@
more information on how each selection target affects the image
processing pipeline inside the subdevice.</para>
+ <para>To retrieve a current selection rectangle applications set the
+ <structfield>pad</structfield> field of a &v4l2-subdev-selection; to the
+ desired pad number as reported by the media API, the
+ <structfield>which</structfield> field to
+ <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant> and the
+ <structfield>target</structfield> to the target selection rectangle. They
+ then call the <constant>VIDIOC_SUBDEV_G_SELECTION</constant> ioctl with a
+ pointer to this structure. The driver fills the members of the
+ <structfield>r</structfield> field or returns &EINVAL; if the input
+ arguments are invalid, or if selection is not supported on the given pad.
+ </para>
+
+ <para>To change a current selection rectangle applications set the
+ <structfield>pad</structfield>, <structfield>which</structfield> and
+ <structfield>target</structfield> fields and all members of the
+ <structfield>r</structfield> field. They then call the
+ <constant>VIDIOC_SUBDEV_S_SELECTION</constant> ioctl with a pointer to this
+ structure. The driver verifies the requested selection rectangle, adjusts it
+ based on the hardware capabilities and configures the device. Upon return
+ the &v4l2-subdev-selection; contains the current selection rectangle as
+ would be returned by a <constant>VIDIOC_SUBDEV_G_SELECTION</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' selection
+ rectangles are not applied to the device by the driver, but are mangled
+ exactly as active selection rectangles and stored in the sub-device file
+ handle. Two applications querying the same sub-device would thus not
+ interfere with each other.</para>
+
+ <para>Drivers must not return an error solely because the requested
+ selection rectangle doesn't match the device capabilities. They must instead
+ modify the rectangle to match what the hardware can provide. The modified
+ selection rectangle should be as close as possible to the original request.
+ </para>
+
<refsect2>
<title>Types of selection targets</title>
--
1.9.1
next prev parent reply other threads:[~2016-05-24 16:51 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-05-24 16:47 [RFC v2 0/21] Media request API Sakari Ailus
2016-05-24 16:47 ` [RFC v2 01/21] media: Add " Sakari Ailus
2016-05-24 16:47 ` [RFC v2 02/21] media: Add media device request state Sakari Ailus
2016-05-24 16:47 ` [RFC v2 03/21] media: Prevent queueing queued requests Sakari Ailus
2016-05-24 16:47 ` [RFC v2 04/21] media: Only requests in IDLE state may be deleted Sakari Ailus
2016-05-24 16:47 ` [RFC v2 05/21] media: Add media_device_request_complete() to mark requests complete Sakari Ailus
2016-05-24 16:47 ` [RFC v2 06/21] media: Add per-entity request data support Sakari Ailus
2016-05-24 16:47 ` [RFC v2 07/21] videodev2.h: Add request field to v4l2_buffer Sakari Ailus
2016-05-24 16:47 ` [RFC v2 08/21] videodev2.h: Add request field to v4l2_pix_format_mplane Sakari Ailus
2016-05-24 16:47 ` [RFC v2 09/21] v4l2-subdev.h: Add request field to format and selection structures Sakari Ailus
2016-05-24 16:47 ` [RFC v2 10/21] v4l: Support the request API in format operations Sakari Ailus
2016-05-24 16:47 ` [RFC v2 11/21] v4l: subdev: Support the request API in format and selection operations Sakari Ailus
2016-05-24 16:47 ` [RFC v2 12/21] vb2: Add allow_requests flag Sakari Ailus
2016-05-24 16:47 ` [RFC v2 13/21] media: Add MEDIA_IOC_DQEVENT Sakari Ailus
2016-05-24 16:47 ` [RFC v2 14/21] media: Make events on request completion optional, disabled by default Sakari Ailus
2016-05-24 16:47 ` [RFC v2 15/21] media: Add poll support Sakari Ailus
2016-05-24 16:47 ` [RFC v2 16/21] DocBook: media: Document the media request API Sakari Ailus
2016-05-24 16:47 ` [RFC v2 17/21] DocBook: media: Document the V4L2 " Sakari Ailus
2016-05-24 16:47 ` Sakari Ailus [this message]
2016-05-24 16:47 ` [RFC v2 19/21] DocBook: media: Document the V4L2 subdev " Sakari Ailus
2016-05-24 16:47 ` [RFC v2 20/21] DocBook: media: Document media events (MEDIA_IOC_DQEVENT IOCTL) Sakari Ailus
2016-05-24 16:47 ` [RFC v2 21/21] DocBook: media: Document request flags Sakari Ailus
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1464108451-28142-19-git-send-email-sakari.ailus@linux.intel.com \
--to=sakari.ailus@linux.intel.com \
--cc=hverkuil@xs4all.nl \
--cc=laurent.pinchart+renesas@ideasonboard.com \
--cc=laurent.pinchart@ideasonboard.com \
--cc=linux-media@vger.kernel.org \
--cc=mchehab@osg.samsung.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).