From patchwork Tue Dec 20 20:27:58 2011 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sakari Ailus X-Patchwork-Id: 8912 Received: from mail.tu-berlin.de ([130.149.7.33]) by www.linuxtv.org with esmtp (Exim 4.72) (envelope-from ) id 1Rd6IV-00033t-NF; Tue, 20 Dec 2011 21:28:28 +0100 X-tubIT-Incoming-IP: 209.132.180.67 Received: from vger.kernel.org ([209.132.180.67]) by mail.tu-berlin.de (exim-4.75/mailfrontend-4) with esmtp id 1Rd6IU-0000op-Bh; Tue, 20 Dec 2011 21:28:27 +0100 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752941Ab1LTU2X (ORCPT + 3 others); Tue, 20 Dec 2011 15:28:23 -0500 Received: from smtp.nokia.com ([147.243.1.47]:34265 "EHLO mgw-sa01.nokia.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752718Ab1LTU2O (ORCPT ); Tue, 20 Dec 2011 15:28:14 -0500 Received: from maxwell.research.nokia.com (maxwell.research.nokia.com [172.21.50.162]) by mgw-sa01.nokia.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id pBKKSAWj018402 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Tue, 20 Dec 2011 22:28:11 +0200 Received: from lanttu (unknown [192.168.239.74]) by maxwell.research.nokia.com (Postfix) with ESMTPS id 7698538663C; Tue, 20 Dec 2011 22:28:10 +0200 (EET) Received: from sakke by lanttu with local (Exim 4.72) (envelope-from ) id 1Rd6IG-0004j0-De; Tue, 20 Dec 2011 22:28:12 +0200 From: Sakari Ailus To: linux-media@vger.kernel.org Cc: laurent.pinchart@ideasonboard.com, dacohen@gmail.com, snjw23@gmail.com Subject: [RFC 06/17] v4l: Add selections documentation. Date: Tue, 20 Dec 2011 22:27:58 +0200 Message-Id: <1324412889-17961-6-git-send-email-sakari.ailus@maxwell.research.nokia.com> X-Mailer: git-send-email 1.7.2.5 In-Reply-To: <4EF0EFC9.6080501@maxwell.research.nokia.com> References: <4EF0EFC9.6080501@maxwell.research.nokia.com> X-Nokia-AV: Clean Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-PMX-Version: 5.6.1.2065439, Antispam-Engine: 2.7.2.376379, Antispam-Data: 2011.12.20.201815 X-PMX-Spam: Gauge=IIIIIIII, Probability=8%, Report=' MULTIPLE_RCPTS 0.1, BODY_SIZE_10000_PLUS 0, __ANY_URI 0, __CP_MEDIA_BODY 0, __HAS_MSGID 0, __HAS_X_MAILER 0, __HAS_X_MAILING_LIST 0, __MIME_TEXT_ONLY 0, __MULTIPLE_RCPTS_CC_X2 0, __SANE_MSGID 0, __TO_MALFORMED_2 0, __TO_NO_NAME 0, __URI_NO_PATH 0, __URI_NO_WWW 0, __URI_NS ' X-LSpam-Score: -1.9 (-) X-LSpam-Report: No, score=-1.9 required=5.0 tests=BAYES_00=-1.9 autolearn=ham From: Sakari Ailus Signed-off-by: Sakari Ailus --- Documentation/DocBook/media/v4l/dev-subdev.xml | 95 +++++++-- Documentation/DocBook/media/v4l/v4l2.xml | 1 + .../media/v4l/vidioc-subdev-g-selection.xml | 226 ++++++++++++++++++++ 3 files changed, 302 insertions(+), 20 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index 0916a73..722db60 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -77,7 +77,7 @@ format, frame width and frame height. Image formats are typically negotiated on video capture and output - devices using the cropping and scaling ioctls. + devices using the format and selection 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. @@ -276,11 +276,11 @@
- Cropping and scaling + Selections: cropping, scaling and composition 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. @@ -288,26 +288,81 @@ &v4l2-rect; by the coordinates of the top left corner and the rectangle size. Both the coordinates and sizes are expressed in pixels. - 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. - - 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. - - 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. - + Scaling operation changes the size of the image by scaling + it to new dimensions. Some sub-devices support it. The scaled + size (width and height) is represented by &v4l2-rect;. In the + case of scaling, top and left will always be zero. Scaling is + configured using &sub-subdev-g-selection; and + V4L2_SUBDEV_SEL_COMPOSE_ACTIVE selection + target on the sink pad of the subdev. The scaling is performed + related to the width and height of the crop rectangle on the + subdev's sink pad. + + As for pad formats, drivers store try and active + rectangles for the selection targets of ACTIVE type . + + On sink 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. + + 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 + containted inside the source image size for the crop + operation. + + The drivers should always use the closest possible + rectangle the user requests on all selection targets, unless + specificly told otherwise. +
+ +
+ Order of configuration and format propagation + + 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 format is propagated within the subdev along the later + processing steps. For example, setting the sink pad format + causes all the selection rectangles and the source pad format to + be set to sink pad format --- if allowed by the hardware, and if + not, then closest possible. The coordinates to a step always + refer to the active size of the previous step. + + + 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. - Cropping behaviour on output pads is not defined. + Sink pad active crop selection. The sink pad crop + defines the performed to the sink pad format. + Sink pad active compose selection. The sink pad compose + rectangle defines the scaling ratio compared to the size of + the sink pad crop rectangle. + + Source pad active crop selection. Crop on the source + pad defines crop performed to the image scaled according to + the sink pad compose rectangle. + + Source pad active compose selection. The source pad + compose defines the size and location of the compose + rectangle. + + 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. + +
+ &sub-subdev-formats; diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index affe1ba..3ff11a6 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -529,6 +529,7 @@ and discussions on the V4L mailing list. &sub-subdev-g-crop; &sub-subdev-g-fmt; &sub-subdev-g-frame-interval; + &sub-subdev-g-selection; &sub-subscribe-event; &sub-mmap; diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml new file mode 100644 index 0000000..5fbcd65 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -0,0 +1,226 @@ + + + ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION + &manvol; + + + + VIDIOC_SUBDEV_G_SELECTION + VIDIOC_SUBDEV_S_SELECTION + Get or set selection rectangles on a subdev pad + + + + + + int ioctl + int fd + int request + struct v4l2_subdev_selection *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION + + + + argp + + + + + + + + + Description + + + Experimental + This is an experimental + interface and may change in the future. + + + 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. + + The selections replace the crop API &sub-subdev-g-crop;. All + the function of the crop API, and more, are supported by the + selections API. + + See Sub-device interface for + more information on how each selection target affects the image + processing pipeline inside the subdevice. + +
+ Types of selection targets + + The are four types of selection targets: active, default, + bounds and padding. The ACTIVE targets are the targets which + configure the hardware. The DEFAULT target provides the default + for the ACTIVE selection. The BOUNDS target will return the + maximum width and height of the target. The PADDED target + provides the width and height for the padded image, and is + directly affected by the ACTIVE target. The PADDED targets may + be configurable depending on the hardware. +
+ + + V4L2 subdev selection targets + + &cs-def; + + + V4L2_SUBDEV_SEL_TGT_CROP_ACTIVE + 0 + Active crop. Defines the cropping + performed by the processing step. + + + V4L2_SUBDEV_SEL_TGT_CROP_DEFAULT + 1 + Default crop rectangle. + + + V4L2_SUBDEV_SEL_TGT_CROP_BOUNDS + 2 + Bounds of the crop rectangle. + + + V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTIVE + 256 + Active compose rectangle. Used to configure scaling + on sink pads and composition on source pads. + + + V4L2_SUBDEV_SEL_TGT_COMPOSE_DEFAULT + 257 + Default compose rectangle. + + + V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS + 258 + Bounds of the compose rectangle. + + + +
+ + + V4L2 subdev selection flags + + &cs-def; + + + V4L2_SUBDEV_SEL_FLAG_SIZE_GE + (1 << 0) + Suggest the driver it should choose greater or + equal rectangle (in size) than was requested. + + + V4L2_SUBDEV_SEL_FLAG_SIZE_LE + (1 << 1) + Suggest the driver it should choose lesser or + equal rectangle (in size) than was requested. + + + V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG + (1 << 2) + 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. + + + +
+ + + struct <structname>v4l2_subdev_selection</structname> + + &cs-str; + + + __u32 + which + Active or try selection, from + &v4l2-subdev-format-whence;. + + + __u32 + pad + Pad number as reported by the media framework. + + + __u32 + target + Target selection rectangle. See + .. + + + __u32 + flags + Flags. See + . + + + &v4l2-rect; + rect + Crop rectangle boundaries, in pixels. + + + __u32 + reserved[8] + Reserved for future extensions. Applications and drivers must + set the array to zero. + + + +
+ + + + + &return-value; + + + + EBUSY + + 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 + VIDIOC_SUBDEV_S_SELECTION + + + + EINVAL + + The &v4l2-subdev-selection; + pad references a non-existing + pad, the which field references a + non-existing format, or the selection target is not + supported on the given subdev pad. + + + + +