From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from mailout4.w1.samsung.com ([210.118.77.14]:24859 "EHLO mailout4.w1.samsung.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1756697Ab2COJz3 (ORCPT ); Thu, 15 Mar 2012 05:55:29 -0400 MIME-version: 1.0 Content-transfer-encoding: 8BIT Content-type: text/plain; charset=UTF-8 Received: from euspt1 ([210.118.77.14]) by mailout4.w1.samsung.com (Sun Java(tm) System Messaging Server 6.3-8.04 (built Jul 29 2009; 32bit)) with ESMTP id <0M0X003TS7KEHA60@mailout4.w1.samsung.com> for linux-media@vger.kernel.org; Thu, 15 Mar 2012 09:55:26 +0000 (GMT) Received: from linux.samsung.com ([106.116.38.10]) by spt1.w1.samsung.com (iPlanet Messaging Server 5.2 Patch 2 (built Jul 14 2004)) with ESMTPA id <0M0X00K807KB8H@spt1.w1.samsung.com> for linux-media@vger.kernel.org; Thu, 15 Mar 2012 09:55:24 +0000 (GMT) Date: Thu, 15 Mar 2012 10:55:25 +0100 From: Sylwester Nawrocki Subject: Re: [PATCH v5 09/35] v4l: Add subdev selections documentation In-reply-to: <1331051596-8261-9-git-send-email-sakari.ailus@iki.fi> To: Sakari Ailus Cc: linux-media@vger.kernel.org, laurent.pinchart@ideasonboard.com, dacohen@gmail.com, snjw23@gmail.com, andriy.shevchenko@linux.intel.com, t.stanislaws@samsung.com, tuukkat76@gmail.com, k.debski@samsung.com, riverful@gmail.com, hverkuil@xs4all.nl, teturtia@gmail.com, pradeep.sawlani@gmail.com Message-id: <4F61BC8D.7060900@samsung.com> References: <20120306163239.GN1075@valkosipuli.localdomain> <1331051596-8261-9-git-send-email-sakari.ailus@iki.fi> Sender: linux-media-owner@vger.kernel.org List-ID: Hi Sakari, On 03/06/2012 05:32 PM, Sakari Ailus wrote: > Add documentation for V4L2 subdev selection API. This changes also > experimental V4L2 subdev API so that scaling now works through selection API > only. > > Signed-off-by: Sakari Ailus > --- > Documentation/DocBook/media/Makefile | 4 +- > Documentation/DocBook/media/v4l/compat.xml | 9 + > Documentation/DocBook/media/v4l/dev-subdev.xml | 202 +++++++++++++++-- > Documentation/DocBook/media/v4l/v4l2.xml | 17 ++- > .../media/v4l/vidioc-subdev-g-selection.xml | 228 ++++++++++++++++++++ > 5 files changed, 433 insertions(+), 27 deletions(-) > cre ate mode 100644 Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml [snip] > 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..9164b85 > --- /dev/null > +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml > @@ -0,0 +1,228 @@ > + > + > + 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 selection API replaces + linkend="vidioc-subdev-g-crop">the old subdev crop API. All > + the function of the crop API, and more, are supported by the > + selections API. > + > + See for > + more information on how each selection target affects the image > + processing pipeline inside the subdevice. > + > +
> + Types of selection targets > + > + There are two types of selection targets: active and bounds. > + The ACTIVE targets are the targets which configure the hardware. > + The BOUNDS target will return a rectangle that contain all > + possible ACTIVE rectangles. > +
> + > +
> + Discovering supported features > + > + To discover which targets are supported, the user can > + perform VIDIOC_SUBDEV_G_SELECTION on them. > + Any unsupported target will return > + EINVAL. > +
> + > + > + V4L2 subdev selection targets > + > + &cs-def; > + > + > + V4L2_SUBDEV_SEL_TGT_CROP_ACTIVE > + 0x0000 > + Active 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_ACTIVE > + 0x0100 > + Active 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. > + > + > + > +
> + > + > + 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. Albeit the driver may choose a lesser size, > + it will only do so due to hardware limitations. Without > + this flag (and > + V4L2_SUBDEV_SEL_FLAG_SIZE_LE) the > + behaviour is to choose the closest possible > + rectangle. > + > + > + V4L2_SUBDEV_SEL_FLAG_SIZE_LE > + (1 << 1) Suggest the driver it > + should choose lesser or equal rectangle (in size) than was > + requested. Albeit the driver may choose a greater size, it > + will only do so due to hardware limitations. > + > + > + 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. Shouldn't it be "Selection rectangle, in pixels." ? > + > + > + __u32 > + reserved[8] > + Reserved for future extensions. Applications and drivers must > + set the array to zero. > + > + > + > +
> + > + -- Regards, Sylwester -- Sylwester Nawrocki 실베스터 나브로츠키 Samsung Poland R&D Center