Re: [PATCH v2 4/6] v4l: Common documentation for selection targets
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<sakari.ailus@xxxxxx>
>> ---
>> 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.
>> <para>V4L2_CTRL_FLAG_VOLATILE was added to signal volatile
>> controls to userspace.</para>
>> </listitem>
>> <listitem>
>> - <para>Add selection API for extended control over cropping and
>> -composing. Does not affect the compatibility of current drivers and
>> -applications. See<link linkend="selection-api"> selection
>> API</link> for
>> -details.</para>
>> + <para>Add selection API for extended control over cropping
>> + and composing. Does not affect the compatibility of current
>> + drivers and applications. See<link
>> + linkend="selection-api"> selection API</link> for
>> + details.</para>
>> </listitem>
>> </orderedlist>
>> </section>
>> 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 @@
>> </para>
>> </section>
>>
>> -<section>
>> +<section id="v4l2-subdev-selections">
>> <title>Selections: cropping, scaling and composition</title>
>>
>> <para>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.</para>
>>
>> -<para>As for pad formats, drivers store try and active rectangles for
>> - the selection targets<xref
>> - linkend="v4l2-subdev-selection-targets">.</xref></para>
>> +<para>As for pad formats, drivers store try and active
>> + rectangles for the selection targets<xref
>> + linkend="v4l2-selections-common">.</xref></para>
>>
>> <para>On sink pads, cropping is applied relative to the
>> current pad format. The pad format represents the image size as
>> @@ -308,7 +308,7 @@
>> <para>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<constant>V4L2_SUBDEV_SEL_TGT_COMPOSE</constant>
>> + using<constant>V4L2_SEL_TGT_COMPOSE</constant>
>> 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.</para>
>> 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.</para>
>> </mediaobject>
>> </figure>
>>
>> -For complete list of the available selection targets see table<xref
>> -linkend="v4l2-sel-target"/>
>> -
>> </section>
>>
>> <section>
>> 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 @@
>> +<section id="v4l2-selections-common">
>> +
>> +<title>Selection targets</title>
>> +
>> +<para>While the V4L2<xref linkend="selection-api"/> and V4L2
>> + subdev<xref linkend="v4l2-subdev-selections"/> 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 <link linkend="selection-api">V4L2 selection
API</link> and <link linkend="v4l2-subdev-selections">V4L2 subdev
selection APIs</link>.
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.</para>
>> +
>> +<para>The meaning of the selection targets may thus be affected on
>> + which of the two interfaces they are used.</para>
>> +
>> +<table pgwide="1" frame="none" id="v4l2-selection-targets-table">
>> +<title>Selection target definitions</title>
>> +<tgroup cols="4">
>> +<colspec colname="c1" />
>> +<colspec colname="c2" />
>> +<colspec colname="c3" />
>> +<colspec colname="c4" />
>> +<colspec colname="c5" />
>> +&cs-def;
>> +<thead>
>> + <row rowsep="1">
>> + <entry align="left">Target name</entry>
>> + <entry align="left">id</entry>
>> + <entry align="left">Definition</entry>
>> + <entry align="left">Valid for V4L2</entry>
>> + <entry align="left">Valid for V4L2 subdev</entry>
>> + </row>
>> +</thead>
>> +<tbody valign="top">
>> + <row>
>> + <entry><constant>V4L2_SEL_TGT_CROP</constant></entry>
>> + <entry>0x0000</entry>
>> + <entry>Crop rectangle. Defines the cropped area.</entry>
>> + <entry>X</entry>
>> + <entry>X</entry>
>> + </row>
>> + <row>
>> +<entry><constant>V4L2_SEL_TGT_CROP_DEFAULT</constant></entry>
>> +<entry>0x0001</entry>
>> +<entry>Suggested cropping rectangle that covers the "whole
>> picture".</entry>
>> + <entry>X</entry>
>> + <entry>O</entry>
>> + </row>
>> + <row>
>> + <entry><constant>V4L2_SEL_TGT_CROP_BOUNDS</constant></entry>
>> + <entry>0x0002</entry>
>> + <entry>Bounds of the crop rectangle. All valid crop
>> + rectangles fit inside the crop bounds rectangle.
>> + </entry>
>> + <entry>X</entry>
>> + <entry>X</entry>
>> + </row>
>> + <row>
>> + <entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry>
>> + <entry>0x0100</entry>
>> + <entry>Compose rectangle. Used to configure scaling
>> + and composition.</entry>
>> + <entry>X</entry>
>> + <entry>X</entry>
>> + </row>
>> + <row>
>> +<entry><constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant></entry>
>> +<entry>0x0101</entry>
>> +<entry>Suggested composition rectangle that covers the "whole
>> picture".</entry>
>> + <entry>X</entry>
>> + <entry>O</entry>
>> + </row>
>> + <row>
>> + <entry><constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant></entry>
>> + <entry>0x0102</entry>
>> + <entry>Bounds of the compose rectangle. All valid compose
>> + rectangles fid inside the compose bounds rectangle.</entry>
>
> typo ? s/fid/fit
Fixed.
>> + <entry>X</entry>
>> + <entry>X</entry>
>> + </row>
>> + <row>
>> +<entry><constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant></entry>
>> +<entry>0x0103</entry>
>> +<entry>The active area and all padding pixels that are inserted or
>> + modified by hardware.</entry>
>> + <entry>X</entry>
>> + <entry>O</entry>
>> + </row>
>> +</tbody>
>> +</tgroup>
>> +</table>
>> +</section>
>> 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.</revremark>
>> &sub-write;
>> </appendix>
>>
>> +<appendix>
>> +<title>Common definitions for V4L2 and V4L2 subdev interfaces</title>
>> +&sub-selections-common;
>> +</appendix>
>> +
>> <appendix id="videodev">
>> <title>Video For Linux Two Header File</title>
>> &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<constant>
>> V4L2_BUF_TYPE_VIDEO_CAPTURE
>> setting the value
>> of&v4l2-selection;<structfield>target</structfield> field
>> to<constant> V4L2_SEL_TGT_CROP</constant> (<constant>
>> V4L2_SEL_TGT_COMPOSE</constant>). Please refer to table<xref
>> -linkend="v4l2-sel-target" /> or<xref linkend="selection-api" /> for
>> additional
>> +linkend="v4l2-selections-common" /> or<xref linkend="selection-api"
>> /> for additional
>> targets. The<structfield>flags</structfield> and<structfield>reserved
>> </structfield> 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<constant>
>> V4L2_BUF_TYPE_VIDEO_CAPTURE
>> setting the value
>> of&v4l2-selection;<structfield>target</structfield> to
>> <constant>V4L2_SEL_TGT_CROP</constant> (<constant>
>> V4L2_SEL_TGT_COMPOSE</constant>). Please refer to table<xref
>> -linkend="v4l2-sel-target" /> or<xref linkend="selection-api" /> for
>> additional
>> +linkend="v4l2-selections-common" /> or<xref linkend="selection-api"
>> /> for additional
>> targets. The&v4l2-rect;<structfield>r</structfield> rectangle need
>> to be
>> set to the desired active area. Field&v4l2-selection;<structfield>
>> reserved
>> </structfield> is ignored and must be filled with zeros. The
>> driver may adjust
>> @@ -154,52 +154,8 @@ exist no rectangle</emphasis> that satisfies the
>> constraints.</para>
>>
>> </refsect1>
>>
>> -<refsect1>
>> -<table frame="none" pgwide="1" id="v4l2-sel-target">
>> -<title>Selection targets.</title>
>> -<tgroup cols="3">
>> - &cs-def;
>> - <tbody valign="top">
>> - <row>
>> -<entry><constant>V4L2_SEL_TGT_CROP</constant></entry>
>> -<entry>0x0000</entry>
>> -<entry>The area that is currently cropped by hardware.</entry>
>> - </row>
>> - <row>
>> -<entry><constant>V4L2_SEL_TGT_CROP_DEFAULT</constant></entry>
>> -<entry>0x0001</entry>
>> -<entry>Suggested cropping rectangle that covers the "whole
>> picture".</entry>
>> - </row>
>> - <row>
>> -<entry><constant>V4L2_SEL_TGT_CROP_BOUNDS</constant></entry>
>> -<entry>0x0002</entry>
>> -<entry>Limits for the cropping rectangle.</entry>
>> - </row>
>> - <row>
>> -<entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry>
>> -<entry>0x0100</entry>
>> -<entry>The area to which data is composed by hardware.</entry>
>> - </row>
>> - <row>
>> -<entry><constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant></entry>
>> -<entry>0x0101</entry>
>> -<entry>Suggested composing rectangle that covers the "whole
>> picture".</entry>
>> - </row>
>> - <row>
>> -<entry><constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant></entry>
>> -<entry>0x0102</entry>
>> -<entry>Limits for the composing rectangle.</entry>
>> - </row>
>> - <row>
>> -<entry><constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant></entry>
>> -<entry>0x0103</entry>
>> -<entry>The active area and all padding pixels that are inserted or
>> - modified by hardware.</entry>
>> - </row>
>> - </tbody>
>> -</tgroup>
>> -</table>
>> -</refsect1>
>> +<para>Selection targets are documented in<xref
>> + linkend="v4l2-selections-common"/>.</para>
>>
>> <refsect1>
>> <table frame="none" pgwide="1" id="v4l2-sel-flags">
>> @@ -253,7 +209,7 @@ exist no rectangle</emphasis> that satisfies the
>> constraints.</para>
>> <row>
>> <entry>__u32</entry>
>> <entry><structfield>target</structfield></entry>
>> -<entry>Used to select between<link linkend="v4l2-sel-target"> cropping
>> +<entry>Used to select between<link linkend="v4l2-selections-common">
>> cropping
>> and composing rectangles</link>.</entry>
>> </row>
>> <row>
>> 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 @@
>> <constant>EINVAL</constant>.</para>
>> </section>
>>
>> -<table pgwide="1" frame="none" id="v4l2-subdev-selection-targets">
>> -<title>V4L2 subdev selection targets</title>
>> -<tgroup cols="3">
>> -&cs-def;
>> - <tbody valign="top">
>> - <row>
>> - <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP</constant></entry>
>> - <entry>0x0000</entry>
>> - <entry>Actual crop. Defines the cropping
>> - performed by the processing step.</entry>
>> - </row>
>> - <row>
>> - <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_BOUNDS</constant></entry>
>> - <entry>0x0002</entry>
>> - <entry>Bounds of the crop rectangle.</entry>
>> - </row>
>> - <row>
>> - <entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE</constant></entry>
>> - <entry>0x0100</entry>
>> - <entry>Actual compose rectangle. Used to configure scaling
>> - on sink pads and composition on source pads.</entry>
>> - </row>
>> - <row>
>> -
>> <entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS</constant></entry>
>> - <entry>0x0102</entry>
>> - <entry>Bounds of the compose rectangle.</entry>
>> - </row>
>> - </tbody>
>> -</tgroup>
>> -</table>
>> +<para>Selection targets are documented in<xref
>> + linkend="v4l2-selections-common"/>.</para>
>>
>> <table pgwide="1" frame="none" id="v4l2-subdev-selection-flags">
>> <title>V4L2 subdev selection flags</title>
>> @@ -173,7 +145,7 @@
>> <entry>__u32</entry>
>> <entry><structfield>target</structfield></entry>
>> <entry>Target selection rectangle. See
>> - <xref linkend="v4l2-subdev-selection-targets">.</xref>.</entry>
>> + <xref linkend="v4l2-selections-common">.</xref>.</entry>
>> </row>
>> <row>
>> <entry>__u32</entry>
>
> --
> Regards,
> Sylwester
Kind regards,
--
Sakari Ailus
sakari.ailus@xxxxxx
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
[Linux Input]
[Video for Linux]
[Mplayer Users]
[Linux USB Devel]
[Linux Audio Users]
[Photos]
[Yosemite Photos]
[Linux Kernel]
[Linux SCSI]
[XFree86]
[Devices]
[Yosemite Backpacking]
