From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from mail-wg0-f44.google.com ([74.125.82.44]:50016 "EHLO mail-wg0-f44.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752227Ab2FMV6S (ORCPT ); Wed, 13 Jun 2012 17:58:18 -0400 Received: by wgbdr13 with SMTP id dr13so1147176wgb.1 for ; Wed, 13 Jun 2012 14:58:16 -0700 (PDT) Message-ID: <4FD90CF6.2090304@gmail.com> Date: Wed, 13 Jun 2012 23:58:14 +0200 From: Sylwester Nawrocki MIME-Version: 1.0 To: Sakari Ailus CC: linux-media@vger.kernel.org, laurent.pinchart@ideasonboard.com, hverkuil@xs4all.nl, t.stanislaws@samsung.com Subject: Re: [PATCH v2 4/6] v4l: Common documentation for selection targets References: <4FD9065B.2030703@iki.fi> <1339623025-6227-4-git-send-email-sakari.ailus@iki.fi> In-Reply-To: <1339623025-6227-4-git-send-email-sakari.ailus@iki.fi> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Sender: linux-media-owner@vger.kernel.org List-ID: Hi Sakari, two minor comments below.. On 06/13/2012 11:30 PM, Sakari Ailus wrote: > 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 > --- > Documentation/DocBook/media/v4l/compat.xml | 9 +- > Documentation/DocBook/media/v4l/dev-subdev.xml | 10 +- > Documentation/DocBook/media/v4l/selection-api.xml | 3 - > .../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, 115 insertions(+), 92 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 + linkend="selection-api"> selection API for > + details. > > > > diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml > index ac715dd..76c4307 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 - linkend="v4l2-subdev-selection-targets">. > +As for pad formats, drivers store try and active > + rectangles for the selection targets + linkend="v4l2-selections-common">. > > 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 > - usingV4L2_SUBDEV_SEL_TGT_COMPOSE > + usingV4L2_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. > diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml > index ac013e5..d652a12 100644 > --- a/Documentation/DocBook/media/v4l/selection-api.xml > +++ b/Documentation/DocBook/media/v4l/selection-api.xml > @@ -53,9 +53,6 @@ cropping and composing rectangles have the same size. > > > > -For complete list of the available selection targets see table -linkend="v4l2-sel-target"/> > - >
> >
> diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml > new file mode 100644 > index 0000000..e8f0b02 > --- /dev/null > +++ b/Documentation/DocBook/media/v4l/selections-common.xml > @@ -0,0 +1,92 @@ > +
> + > +Selection targets > + > +While the V4L2 and V4L2 > + subdev selection APIs are very This sentence isn't quite correct. although I haven't looked myself how this could be improved, wouldn't it be there any way to use custom text for the hyperlink, not what get's pasted automatically ? It doesn't quite parse now. > + similar, there's one fundamental difference between the two. On > + sub-device API, the selection rectangle is refers to the media bus > + format, and is bound to a sub-device and a pad. On the V4L2 > + interface the selection rectangles refer to the in-memory pixel > + format and a video device's buffer queue. > + > +The 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. > + X > + X > + > + > +V4L2_SEL_TGT_CROP_DEFAULT > +0x0001 > +Suggested cropping rectangle that covers the "whole picture". > + X > + O > + > + > + V4L2_SEL_TGT_CROP_BOUNDS > + 0x0002 > + Bounds of the crop rectangle. All valid crop > + rectangles fit inside the crop bounds rectangle. > + > + X > + X > + > + > + V4L2_SEL_TGT_COMPOSE > + 0x0100 > + Compose rectangle. Used to configure scaling > + and composition. > + X > + X > + > + > +V4L2_SEL_TGT_COMPOSE_DEFAULT > +0x0101 > +Suggested composition rectangle that covers the "whole picture". > + X > + O > + > + > + V4L2_SEL_TGT_COMPOSE_BOUNDS > + 0x0102 > + Bounds of the compose rectangle. All valid compose > + rectangles fid inside the compose bounds rectangle. typo ? s/fid/fit > + X > + X > + > + > +V4L2_SEL_TGT_COMPOSE_PADDED > +0x0103 > +The active area and all padding pixels that are inserted or > + modified by hardware. > + X > + O > + > + > + > +
> +
> diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml > index 015c561..87d0f4f 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 -linkend="v4l2-sel-target" /> or for additional > +linkend="v4l2-selections-common" /> or for additional > targets. Theflags andreserved > 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 -linkend="v4l2-sel-target" /> 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 + linkend="v4l2-selections-common"/>. > > > > @@ -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 96ab51e..fa4063a 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 + linkend="v4l2-selections-common"/>. > > > V4L2 subdev selection flags > @@ -173,7 +145,7 @@ > __u32 > target > Target selection rectangle. See > - .. > + .. > > > __u32 -- Regards, Sylwester