From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from smtp.nokia.com ([147.243.1.47]:40800 "EHLO mgw-sa01.nokia.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752650Ab2FMWhc (ORCPT ); Wed, 13 Jun 2012 18:37:32 -0400 Message-ID: <4FD9161E.2050804@iki.fi> Date: Thu, 14 Jun 2012 01:37:18 +0300 From: Sakari Ailus MIME-Version: 1.0 To: Sylwester Nawrocki 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> <4FD90CF6.2090304@gmail.com> In-Reply-To: <4FD90CF6.2090304@gmail.com> Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Sender: linux-media-owner@vger.kernel.org List-ID: Hi Sylwester, Sylwester Nawrocki wrote: > Hi Sakari, > > two minor comments below.. Thanks for your comments. > 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. I replaced that with V4L2 selection API and V4L2 subdev selection APIs. I updated the HTML documentation to reflect this. >> + 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 Fixed. >> + 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 Kind regards, -- Sakari Ailus sakari.ailus@iki.fi