diff mbox

[v2] v4l: doc: Clarify v4l2_mbus_fmt height definition

Message ID 1515434106-18747-1-git-send-email-kieran.bingham@ideasonboard.com (mailing list archive)
State Not Applicable
Delegated to: Geert Uytterhoeven
Headers show

Commit Message

Kieran Bingham Jan. 8, 2018, 5:55 p.m. UTC
The v4l2_mbus_fmt width and height corresponds directly with the
v4l2_pix_format definitions, yet the differences in documentation make
it ambiguous what to do in the event of field heights.

Clarify this using the same text as is provided for the v4l2_pix_format
which is explicit on the matter, and by matching the terminology of
'image height' rather than the misleading 'frame height'.

Signed-off-by: Kieran Bingham <kieran.bingham+renesas@ideasonboard.com>
---
v2:
 - Duplicated explicit text from v4l2_pix_format rather than
   referencing it.

 Documentation/media/uapi/v4l/subdev-formats.rst | 8 ++++++--
 include/uapi/linux/v4l2-mediabus.h              | 4 ++--
 2 files changed, 8 insertions(+), 4 deletions(-)

Comments

Sakari Ailus Jan. 8, 2018, 9:13 p.m. UTC | #1
Hi Kieran,

Thanks for the update.

On Mon, Jan 08, 2018 at 05:55:24PM +0000, Kieran Bingham wrote:
> The v4l2_mbus_fmt width and height corresponds directly with the
> v4l2_pix_format definitions, yet the differences in documentation make
> it ambiguous what to do in the event of field heights.
> 
> Clarify this using the same text as is provided for the v4l2_pix_format
> which is explicit on the matter, and by matching the terminology of
> 'image height' rather than the misleading 'frame height'.
> 
> Signed-off-by: Kieran Bingham <kieran.bingham+renesas@ideasonboard.com>

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Niklas Söderlund Jan. 8, 2018, 10:38 p.m. UTC | #2
Hi Kieran,

Thanks for your patch.

On 2018-01-08 17:55:24 +0000, Kieran Bingham wrote:
> The v4l2_mbus_fmt width and height corresponds directly with the
> v4l2_pix_format definitions, yet the differences in documentation make
> it ambiguous what to do in the event of field heights.
> 
> Clarify this using the same text as is provided for the v4l2_pix_format
> which is explicit on the matter, and by matching the terminology of
> 'image height' rather than the misleading 'frame height'.
> 
> Signed-off-by: Kieran Bingham <kieran.bingham+renesas@ideasonboard.com>

Reviewed-by: Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>

> ---
> v2:
>  - Duplicated explicit text from v4l2_pix_format rather than
>    referencing it.
> 
>  Documentation/media/uapi/v4l/subdev-formats.rst | 8 ++++++--
>  include/uapi/linux/v4l2-mediabus.h              | 4 ++--
>  2 files changed, 8 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst
> index b1eea44550e1..9fcabe7f9367 100644
> --- a/Documentation/media/uapi/v4l/subdev-formats.rst
> +++ b/Documentation/media/uapi/v4l/subdev-formats.rst
> @@ -16,10 +16,14 @@ Media Bus Formats
>  
>      * - __u32
>        - ``width``
> -      - Image width, in pixels.
> +      - Image width in pixels.
>      * - __u32
>        - ``height``
> -      - Image height, in pixels.
> +      - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
> +	``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
> +	refers to the number of lines in the field, otherwise it refers to
> +	the number of lines in the frame (which is twice the field height
> +	for interlaced formats).
>      * - __u32
>        - ``code``
>        - Format code, from enum
> diff --git a/include/uapi/linux/v4l2-mediabus.h b/include/uapi/linux/v4l2-mediabus.h
> index 6e20de63ec59..123a231001a8 100644
> --- a/include/uapi/linux/v4l2-mediabus.h
> +++ b/include/uapi/linux/v4l2-mediabus.h
> @@ -18,8 +18,8 @@
>  
>  /**
>   * struct v4l2_mbus_framefmt - frame format on the media bus
> - * @width:	frame width
> - * @height:	frame height
> + * @width:	image width
> + * @height:	image height
>   * @code:	data format code (from enum v4l2_mbus_pixelcode)
>   * @field:	used interlacing type (from enum v4l2_field)
>   * @colorspace:	colorspace of the data (from enum v4l2_colorspace)
> -- 
> 2.7.4
>
Hans Verkuil Jan. 9, 2018, 7:29 a.m. UTC | #3
On 01/08/2018 06:55 PM, Kieran Bingham wrote:
> The v4l2_mbus_fmt width and height corresponds directly with the
> v4l2_pix_format definitions, yet the differences in documentation make
> it ambiguous what to do in the event of field heights.
> 
> Clarify this using the same text as is provided for the v4l2_pix_format
> which is explicit on the matter, and by matching the terminology of
> 'image height' rather than the misleading 'frame height'.
> 
> Signed-off-by: Kieran Bingham <kieran.bingham+renesas@ideasonboard.com>

Reviewed-by: Hans Verkuil <hans.verkuil@cisco.com>

Regards,

	Hans

> ---
> v2:
>  - Duplicated explicit text from v4l2_pix_format rather than
>    referencing it.
> 
>  Documentation/media/uapi/v4l/subdev-formats.rst | 8 ++++++--
>  include/uapi/linux/v4l2-mediabus.h              | 4 ++--
>  2 files changed, 8 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst
> index b1eea44550e1..9fcabe7f9367 100644
> --- a/Documentation/media/uapi/v4l/subdev-formats.rst
> +++ b/Documentation/media/uapi/v4l/subdev-formats.rst
> @@ -16,10 +16,14 @@ Media Bus Formats
>  
>      * - __u32
>        - ``width``
> -      - Image width, in pixels.
> +      - Image width in pixels.
>      * - __u32
>        - ``height``
> -      - Image height, in pixels.
> +      - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
> +	``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
> +	refers to the number of lines in the field, otherwise it refers to
> +	the number of lines in the frame (which is twice the field height
> +	for interlaced formats).
>      * - __u32
>        - ``code``
>        - Format code, from enum
> diff --git a/include/uapi/linux/v4l2-mediabus.h b/include/uapi/linux/v4l2-mediabus.h
> index 6e20de63ec59..123a231001a8 100644
> --- a/include/uapi/linux/v4l2-mediabus.h
> +++ b/include/uapi/linux/v4l2-mediabus.h
> @@ -18,8 +18,8 @@
>  
>  /**
>   * struct v4l2_mbus_framefmt - frame format on the media bus
> - * @width:	frame width
> - * @height:	frame height
> + * @width:	image width
> + * @height:	image height
>   * @code:	data format code (from enum v4l2_mbus_pixelcode)
>   * @field:	used interlacing type (from enum v4l2_field)
>   * @colorspace:	colorspace of the data (from enum v4l2_colorspace)
>
diff mbox

Patch

diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst
index b1eea44550e1..9fcabe7f9367 100644
--- a/Documentation/media/uapi/v4l/subdev-formats.rst
+++ b/Documentation/media/uapi/v4l/subdev-formats.rst
@@ -16,10 +16,14 @@  Media Bus Formats
 
     * - __u32
       - ``width``
-      - Image width, in pixels.
+      - Image width in pixels.
     * - __u32
       - ``height``
-      - Image height, in pixels.
+      - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
+	``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
+	refers to the number of lines in the field, otherwise it refers to
+	the number of lines in the frame (which is twice the field height
+	for interlaced formats).
     * - __u32
       - ``code``
       - Format code, from enum
diff --git a/include/uapi/linux/v4l2-mediabus.h b/include/uapi/linux/v4l2-mediabus.h
index 6e20de63ec59..123a231001a8 100644
--- a/include/uapi/linux/v4l2-mediabus.h
+++ b/include/uapi/linux/v4l2-mediabus.h
@@ -18,8 +18,8 @@ 
 
 /**
  * struct v4l2_mbus_framefmt - frame format on the media bus
- * @width:	frame width
- * @height:	frame height
+ * @width:	image width
+ * @height:	image height
  * @code:	data format code (from enum v4l2_mbus_pixelcode)
  * @field:	used interlacing type (from enum v4l2_field)
  * @colorspace:	colorspace of the data (from enum v4l2_colorspace)