From: Sylwester Nawrocki <sylwester.nawrocki@gmail.com>
To: Sakari Ailus <sakari.ailus@iki.fi>
Cc: linux-media@vger.kernel.org, t.stanislaws@samsung.com,
laurent.pinchart@ideasonboard.com, hverkuil@xs4all.nl
Subject: Re: [PATCH 6/8] v4l: Unify selection flags documentation
Date: Sat, 30 Jun 2012 23:13:40 +0200 [thread overview]
Message-ID: <4FEF6C04.8010405@gmail.com> (raw)
In-Reply-To: <1341075839-18586-6-git-send-email-sakari.ailus@iki.fi>
On 06/30/2012 07:03 PM, Sakari Ailus wrote:
> As for the selection targets, the selection flags are now the same on V4L2
> and V4L2 subdev interfaces. Also document them so.
>
> Signed-off-by: Sakari Ailus<sakari.ailus@iki.fi>
> ---
> Documentation/DocBook/media/v4l/dev-subdev.xml | 6 +-
> Documentation/DocBook/media/v4l/selection-api.xml | 6 +-
> .../DocBook/media/v4l/selections-common.xml | 226 +++++++++++++-------
> .../DocBook/media/v4l/vidioc-g-selection.xml | 27 +---
> .../media/v4l/vidioc-subdev-g-selection.xml | 39 +----
> 5 files changed, 159 insertions(+), 145 deletions(-)
>
> diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml
> index afeb196..a3d9dd0 100644
> --- a/Documentation/DocBook/media/v4l/dev-subdev.xml
> +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml
> @@ -323,10 +323,10 @@
> <para>The drivers should always use the closest possible
> rectangle the user requests on all selection targets, unless
> specifically told otherwise.
> -<constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant> and
> -<constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant> flags may be
> +<constant>V4L2_SEL_FLAG_GE</constant> and
> +<constant>V4L2_SEL_FLAG_LE</constant> flags may be
> used to round the image size either up or down.<xref
> - linkend="v4l2-subdev-selection-flags"></xref></para>
> + linkend="v4l2-selection-flags" /></para>
> </section>
>
> <section>
> diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml
> index 24dec10..e7ed507 100644
> --- a/Documentation/DocBook/media/v4l/selection-api.xml
> +++ b/Documentation/DocBook/media/v4l/selection-api.xml
> @@ -55,7 +55,7 @@ cropping and composing rectangles have the same size.</para>
>
> </section>
>
> - See<xref linkend="v4l2-selection-targets-table" /> for more
> + See<xref linkend="v4l2-selection-targets" /> for more
> information.
>
> <section>
> @@ -74,7 +74,7 @@ cropping/composing rectangles may have to be aligned, and both the source and
> the sink may have arbitrary upper and lower size limits. Therefore, as usual,
> drivers are expected to adjust the requested parameters and return the actual
> values selected. An application can control the rounding behaviour using<link
> -linkend="v4l2-sel-flags"> constraint flags</link>.</para>
> +linkend="v4l2-selection-flags"> constraint flags</link>.</para>
>
> <section>
>
> @@ -117,7 +117,7 @@ the bounds rectangle. The composing rectangle must lie completely inside bounds
> rectangle. The driver must adjust the composing rectangle to fit to the
> bounding limits. Moreover, the driver can perform other adjustments according
> to hardware limitations. The application can control rounding behaviour using
> -<link linkend="v4l2-sel-flags"> constraint flags</link>.</para>
> +<link linkend="v4l2-selection-flags"> constraint flags</link>.</para>
>
> <para>For capture devices the default composing rectangle is queried using
> <constant> V4L2_SEL_TGT_COMPOSE_DEFAULT</constant>. It is usually equal to the
> diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml
> index d0411ab..7cec5c1 100644
> --- a/Documentation/DocBook/media/v4l/selections-common.xml
> +++ b/Documentation/DocBook/media/v4l/selections-common.xml
> @@ -1,6 +1,6 @@
> <section id="v4l2-selections-common">
>
> -<title>Selection targets</title>
> +<title>Common selection definitions</title>
>
> <para>While the<link linkend="selection-api">V4L2 selection
> API</link> and<link linkend="v4l2-subdev-selections">V4L2 subdev
> @@ -10,83 +10,155 @@
> sub-device's pad. On the V4L2 interface the selection rectangles
> refer to the in-memory pixel format.</para>
>
> -<para>The precise meaning of the selection targets may thus be
> - affected on which of the two interfaces they are used.</para>
> +<para>This section defines the common definitions of the
> + selection interfaces on the two APIs.</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>Yes</entry>
> - <entry>Yes</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>Yes</entry>
> - <entry>No</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>Yes</entry>
> - <entry>Yes</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>Yes</entry>
> - <entry>Yes</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>Yes</entry>
> - <entry>No</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 fit inside the compose bounds rectangle.</entry>
> - <entry>Yes</entry>
> - <entry>Yes</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
> +<section id="v4l2-selection-targets">
> +
> +<title>Selection targets</title>
> +
> +<para>The precise meaning of the selection targets may be
> + dependent 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">
s/4/5
> + <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>Yes</entry>
> + <entry>Yes</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>Yes</entry>
> + <entry>No</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>Yes</entry>
> + <entry>Yes</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>Yes</entry>
> + <entry>Yes</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>Yes</entry>
> + <entry>No</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 fit inside the compose bounds rectangle.</entry>
> + <entry>Yes</entry>
> + <entry>Yes</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>Yes</entry>
> - <entry>No</entry>
> + <entry>Yes</entry>
> + <entry>No</entry>
> + </row>
> + </tbody>
> +</tgroup>
> +</table>
> +
> +</section>
> +
> +<section id="v4l2-selection-flags">
> +
> +<title>Selection flags</title>
> +
> +<table pgwide="1" frame="none" id="v4l2-selection-flags-table">
> +<title>Selection flag definitions</title>
> +<tgroup cols="4">
s/4/5
> + <colspec colname="c1" />
> + <colspec colname="c2" />
> + <colspec colname="c3" />
> + <colspec colname="c4" />
> + <colspec colname="c5" />
> + &cs-def;
> + <thead>
> + <row rowsep="1">
> + <entry align="left">Flag 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>
> -</tbody>
> -</tgroup>
> -</table>
> + </thead>
> + <tbody valign="top">
> + <row>
> + <entry><constant>V4L2_SEL_FLAG_GE</constant></entry>
> + <entry>(1<< 0)</entry>
This field is quite badly formatted, due to too small width of column c2.
I couldn't fix that with "colwidth" though. It's minor issue anyway.
Acked-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
next prev parent reply other threads:[~2012-06-30 21:13 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2012-06-30 17:05 [PATCH v5 0/8] V4L2 and V4L2 subdev selection target and flag changes Sakari Ailus
2012-06-30 17:03 ` [PATCH 1/8] V4L: Remove "_ACTIVE" from the selection target name definitions Sakari Ailus
2012-06-30 17:03 ` [PATCH 2/8] v4l: Remove "_ACTUAL" from subdev selection API target definition names Sakari Ailus
2012-06-30 20:21 ` Sylwester Nawrocki
2012-06-30 17:03 ` [PATCH 3/8] v4l: Unify selection targets across V4L2 and V4L2 subdev interfaces Sakari Ailus
2012-06-30 20:22 ` Sylwester Nawrocki
2012-07-01 11:13 ` Sakari Ailus
2012-07-01 11:45 ` Sylwester Nawrocki
2012-06-30 17:03 ` [PATCH 4/8] v4l: Common documentation for selection targets Sakari Ailus
2012-06-30 21:01 ` Sylwester Nawrocki
2012-06-30 17:03 ` [PATCH 5/8] v4l: Unify selection flags Sakari Ailus
2012-06-30 20:23 ` Sylwester Nawrocki
2012-06-30 17:03 ` [PATCH 6/8] v4l: Unify selection flags documentation Sakari Ailus
2012-06-30 21:13 ` Sylwester Nawrocki [this message]
2012-06-30 17:03 ` [PATCH 7/8] Feature removal: V4L2 selections API target and flag definitions Sakari Ailus
2012-06-30 17:03 ` [PATCH 8/8] v4l: Correct conflicting V4L2 subdev selection API documentation Sakari Ailus
2012-06-30 20:29 ` Sylwester Nawrocki
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=4FEF6C04.8010405@gmail.com \
--to=sylwester.nawrocki@gmail.com \
--cc=hverkuil@xs4all.nl \
--cc=laurent.pinchart@ideasonboard.com \
--cc=linux-media@vger.kernel.org \
--cc=sakari.ailus@iki.fi \
--cc=t.stanislaws@samsung.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).