Re: [PATCH v4 2/7] v4l: Remove "_ACTUAL" from subdev selection API target definition names

[Sakari Ailus <sakari.ailus@iki.fi>]

Hi Laurent,

Laurent Pinchart wrote:
> Hi Sakari,
> 
> Thanks for the patch.

Thanks for the comments!

> On Friday 15 June 2012 16:44:35 Sakari Ailus wrote:
>> The string "_ACTUAL" does not say anything more about the target names. Drop
>> it. V4L2 selection API was changed by "V4L: Remove "_ACTIVE" from the
>> selection target name definitions" by Sylwester Nawrocki. This patch does
>> the same for the V4L2 subdev API.
>>
>> Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi>
>> ---
>>  Documentation/DocBook/media/v4l/dev-subdev.xml     |   25
>> +++++++++---------- .../media/v4l/vidioc-subdev-g-selection.xml        |  
>> 12 ++++---- drivers/media/video/omap3isp/ispccdc.c             |    4 +-
>>  drivers/media/video/omap3isp/isppreview.c          |    4 +-
>>  drivers/media/video/omap3isp/ispresizer.c          |    4 +-
>>  drivers/media/video/smiapp/smiapp-core.c           |   22 ++++++++--------
>>  drivers/media/video/v4l2-subdev.c                  |    4 +-
>>  include/linux/v4l2-subdev.h                        |    4 +-
>>  8 files changed, 39 insertions(+), 40 deletions(-)
>>
>> diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml
>> b/Documentation/DocBook/media/v4l/dev-subdev.xml index 4afcbbe..ac715dd
>> 100644
>> --- a/Documentation/DocBook/media/v4l/dev-subdev.xml
>> +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml
>> @@ -289,8 +289,8 @@
>>        &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 of ACTUAL type <xref
>> +      <para>As for pad formats, drivers store try and active rectangles for
>> +      the selection targets <xref
>>        linkend="v4l2-subdev-selection-targets">.</xref></para>
> 
> Could you please also fix the xref issue ? According to 
> http://www.docbook.org/tdg/en/html/xref.html, the xref element is supposed to 
> be empty. You can either use something like
> 
> ... the selection targets described in <xref .../>
> 
> or a link element around "selection targets".

Fixed the xref.

>>        <para>On sink pads, cropping is applied relative to the
>> @@ -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_COMPOSE_ACTUAL</constant>
>> +      using <constant>V4L2_SUBDEV_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>
>> @@ -333,22 +333,21 @@
>>        <title>Types of selection targets</title>
>>
>>        <section>
>> -	<title>ACTUAL targets</title>
>> +	<title>Actual targets</title>
>>
>> -	<para>ACTUAL targets reflect the actual hardware configuration
>> -	at any point of time. There is a BOUNDS target
>> -	corresponding to every ACTUAL.</para>
>> +	<para>Actual targets (without a postfix) reflect the actual hardware
>> +	configuration at any point of time.</para>
>>        </section>
> 
> Don't we have a bounds target for every actual target ?

Oh. That probably got accidentally removed. I'll fix it.

>>        <section>
>>  	<title>BOUNDS targets</title>
>>
>> -	<para>BOUNDS targets is the smallest rectangle that contains
>> -	all valid ACTUAL rectangles. It may not be possible to set the
>> -	ACTUAL rectangle as large as the BOUNDS rectangle, however.
>> -	This may be because e.g. a sensor's pixel array is not
>> -	rectangular but cross-shaped or round. The maximum size may
>> -	also be smaller than the BOUNDS rectangle.</para>
>> +	<para>BOUNDS targets is the smallest rectangle that contains all
>> +	valid actual rectangles. It may not be possible to set the actual
>> +	rectangle as large as the BOUNDS rectangle, however. This may be
>> +	because e.g. a sensor's pixel array is not rectangular but
>> +	cross-shaped or round. The maximum size may also be smaller than the
>> +	BOUNDS rectangle.</para>
>>        </section>
>>
>>      </section>
>> diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
>> b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index
>> 208e9f0..96ab51e 100644
>> --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
>> +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
>> @@ -72,10 +72,10 @@
>>      <section>
>>        <title>Types of selection targets</title>
>>
>> -      <para>There are two types of selection targets: actual and bounds.
>> -      The ACTUAL targets are the targets which configure the hardware.
>> -      The BOUNDS target will return a rectangle that contain all
>> -      possible ACTUAL rectangles.</para>
>> +      <para>There are two types of selection targets: plain and bounds. The
> 
> plain or actual ?

Fixed.

>> +      actual targets are the targets which configure the hardware. The
>> BOUNDS +      target will return a rectangle that contain all possible
>> actual +      rectangles.</para>
>>      </section>
>>
>>      <section>
>> @@ -93,7 +93,7 @@
>>          &cs-def;
>>  	<tbody valign="top">
>>  	  <row>
>> -	    <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL</constant></entry>
>> +	    <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP</constant></entry>
>>  	    <entry>0x0000</entry>
>>  	    <entry>Actual crop. Defines the cropping
>>  	    performed by the processing step.</entry>
>> @@ -104,7 +104,7 @@
>>  	    <entry>Bounds of the crop rectangle.</entry>
>>  	  </row>
>>  	  <row>
>> -	    
> <entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL</constant></entry>
>> +	    <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>
> 

Cheers,

-- 
Sakari Ailus
sakari.ailus@iki.fi