From patchwork Sat Jun 30 17:03:55 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sakari Ailus X-Patchwork-Id: 1134661 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-process-083081@patchwork1.kernel.org Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by patchwork1.kernel.org (Postfix) with ESMTP id 8FDFB3FE37 for ; Sat, 30 Jun 2012 17:05:49 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753435Ab2F3RFq (ORCPT ); Sat, 30 Jun 2012 13:05:46 -0400 Received: from smtp.nokia.com ([147.243.1.48]:46157 "EHLO mgw-sa02.nokia.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752797Ab2F3RFm (ORCPT ); Sat, 30 Jun 2012 13:05:42 -0400 Received: from maxwell.research.nokia.com (maxwell.research.nokia.com [172.21.199.25]) by mgw-sa02.nokia.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id q5UH5Rak027457 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 30 Jun 2012 20:05:28 +0300 Received: from kaali.localdomain (kaali.localdomain [192.168.239.7]) by maxwell.research.nokia.com (Postfix) with ESMTPS id 3E8DC1F507F; Sat, 30 Jun 2012 20:09:51 +0300 (EEST) Received: from sailus by kaali.localdomain with local (Exim 4.72) (envelope-from ) id 1Sl15U-0004qi-P0; Sat, 30 Jun 2012 20:04:00 +0300 From: Sakari Ailus To: linux-media@vger.kernel.org Cc: sylwester.nawrocki@gmail.com, t.stanislaws@samsung.com, laurent.pinchart@ideasonboard.com, hverkuil@xs4all.nl Subject: [PATCH 4/8] v4l: Common documentation for selection targets Date: Sat, 30 Jun 2012 20:03:55 +0300 Message-Id: <1341075839-18586-4-git-send-email-sakari.ailus@iki.fi> X-Mailer: git-send-email 1.7.2.5 In-Reply-To: <20120630170506.GE19384@valkosipuli.retiisi.org.uk> References: <20120630170506.GE19384@valkosipuli.retiisi.org.uk> X-Nokia-AV: Clean Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org 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: Sakari Ailus Acked-by: Sylwester Nawrocki --- Documentation/DocBook/media/v4l/compat.xml | 9 +- Documentation/DocBook/media/v4l/dev-subdev.xml | 12 ++-- Documentation/DocBook/media/v4l/selection-api.xml | 6 +- .../DocBook/media/v4l/selections-common.xml | 92 ++++++++++++++++++++ Documentation/DocBook/media/v4l/v4l2.xml | 5 + .../DocBook/media/v4l/vidioc-g-selection.xml | 54 +----------- .../media/v4l/vidioc-subdev-g-selection.xml | 34 +------- 7 files changed, 119 insertions(+), 93 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/selections-common.xml diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index ea42ef8..162a0ba 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2377,10 +2377,11 @@ that used it. It was originally scheduled for removal in 2.6.35. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace. - Add selection API for extended control over cropping and -composing. Does not affect the compatibility of current drivers and -applications. See selection API for -details. + Add selection API for extended control over cropping + and composing. Does not affect the compatibility of current + drivers and applications. See selection API for + details. diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index e88d5ea..afeb196 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -276,7 +276,7 @@ -
+
Selections: cropping, scaling and composition 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. - As for pad formats, drivers store try and active rectangles for - the selection targets . + As for pad formats, drivers store try and active + rectangles for the selection targets . On sink pads, cropping is applied relative to the current pad format. The pad format represents the image size as @@ -308,7 +308,7 @@ 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 V4L2_SUBDEV_SEL_TGT_COMPOSE + using V4L2_SEL_TGT_COMPOSE 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. @@ -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 - V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG flag. This + V4L2_SEL_FLAG_KEEP_CONFIG 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 diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index ac013e5..24dec10 100644 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -53,11 +53,11 @@ cropping and composing rectangles have the same size. -For complete list of the available selection targets see table -
+ See for more + information. +
Configuration diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml new file mode 100644 index 0000000..d0411ab --- /dev/null +++ b/Documentation/DocBook/media/v4l/selections-common.xml @@ -0,0 +1,92 @@ +
+ + Selection targets + + While the V4L2 selection + API and V4L2 subdev + selection APIs 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. + + The precise meaning of the selection targets may thus be + affected on which of the two interfaces they are used. + + + Selection target definitions + + + + + + + &cs-def; + + + Target name + id + Definition + Valid for V4L2 + Valid for V4L2 subdev + + + + + V4L2_SEL_TGT_CROP + 0x0000 + Crop rectangle. Defines the cropped area. + Yes + Yes + + + V4L2_SEL_TGT_CROP_DEFAULT + 0x0001 + Suggested cropping rectangle that covers the "whole picture". + Yes + No + + + V4L2_SEL_TGT_CROP_BOUNDS + 0x0002 + Bounds of the crop rectangle. All valid crop + rectangles fit inside the crop bounds rectangle. + + Yes + Yes + + + V4L2_SEL_TGT_COMPOSE + 0x0100 + Compose rectangle. Used to configure scaling + and composition. + Yes + Yes + + + V4L2_SEL_TGT_COMPOSE_DEFAULT + 0x0101 + Suggested composition rectangle that covers the "whole picture". + Yes + No + + + V4L2_SEL_TGT_COMPOSE_BOUNDS + 0x0102 + Bounds of the compose rectangle. All valid compose + rectangles fit inside the compose bounds rectangle. + Yes + Yes + + + V4L2_SEL_TGT_COMPOSE_PADDED + 0x0103 + The active area and all padding pixels that are inserted or + modified by hardware. + Yes + No + + + +
+
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 008c2d7..36bafc4 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -589,6 +589,11 @@ and discussions on the V4L mailing list. &sub-write; + + Common definitions for V4L2 and V4L2 subdev interfaces + &sub-selections-common; + + Video For Linux Two Header File &sub-videodev2-h; diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index 6376e57..c6f8325 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -67,7 +67,7 @@ Do not use multiplanar buffers. Use V4L2_BUF_TYPE_VIDEO_CAPTURE setting the value of &v4l2-selection; target field to V4L2_SEL_TGT_CROP ( V4L2_SEL_TGT_COMPOSE ). Please refer to table or for additional +linkend="v4l2-selections-common" /> or for additional targets. The flags and reserved fields of &v4l2-selection; are ignored and they must be filled with zeros. The driver fills the rest of the structure or @@ -88,7 +88,7 @@ use multiplanar buffers. Use V4L2_BUF_TYPE_VIDEO_CAPTURE setting the value of &v4l2-selection; target to V4L2_SEL_TGT_CROP ( V4L2_SEL_TGT_COMPOSE ). Please refer to table or for additional +linkend="v4l2-selections-common" /> or for additional targets. The &v4l2-rect; r rectangle need to be set to the desired active area. Field &v4l2-selection; reserved is ignored and must be filled with zeros. The driver may adjust @@ -154,52 +154,8 @@ exist no rectangle that satisfies the constraints. - - - Selection targets. - - &cs-def; - - - V4L2_SEL_TGT_CROP - 0x0000 - The area that is currently cropped by hardware. - - - V4L2_SEL_TGT_CROP_DEFAULT - 0x0001 - Suggested cropping rectangle that covers the "whole picture". - - - V4L2_SEL_TGT_CROP_BOUNDS - 0x0002 - Limits for the cropping rectangle. - - - V4L2_SEL_TGT_COMPOSE - 0x0100 - The area to which data is composed by hardware. - - - V4L2_SEL_TGT_COMPOSE_DEFAULT - 0x0101 - Suggested composing rectangle that covers the "whole picture". - - - V4L2_SEL_TGT_COMPOSE_BOUNDS - 0x0102 - Limits for the composing rectangle. - - - V4L2_SEL_TGT_COMPOSE_PADDED - 0x0103 - The active area and all padding pixels that are inserted or - modified by hardware. - - - -
- + Selection targets are documented in . @@ -253,7 +209,7 @@ exist no rectangle that satisfies the constraints. __u32 target - Used to select between cropping + Used to select between cropping and composing rectangles. diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index 4c44808..ace1478 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -87,36 +87,8 @@ EINVAL. -
- V4L2 subdev selection targets - - &cs-def; - - - V4L2_SUBDEV_SEL_TGT_CROP - 0x0000 - Actual crop. Defines the cropping - performed by the processing step. - - - V4L2_SUBDEV_SEL_TGT_CROP_BOUNDS - 0x0002 - Bounds of the crop rectangle. - - - V4L2_SUBDEV_SEL_TGT_COMPOSE - 0x0100 - Actual compose rectangle. Used to configure scaling - on sink pads and composition on source pads. - - - V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS - 0x0102 - Bounds of the compose rectangle. - - - -
+ Selection targets are documented in . V4L2 subdev selection flags @@ -173,7 +145,7 @@ __u32targetTarget selection rectangle. See - .. + . __u32