[PATCH v2 0/2] Add explicit digital gain control, document gain controls better

[PATCH v2 0/2] Add explicit digital gain control, document gain controls better

[Sakari Ailus]

Hi folks,

This set includes two patches: one that adds digital gain control and
another that better documents the relationship between the gain controls.

changes since v1:

- Say that the no-gain digital gain configuration is typically the
  default. This was slightly unclear in the previous version and could
  have been understood as the default being 0x100.

Sakari Ailus (2):
  v4l: ctrls: Add a control for digital gain
  v4l: controls: Improve documentation for V4L2_CID_GAIN

 Documentation/media/uapi/v4l/control.rst           | 6 ++++++
 Documentation/media/uapi/v4l/extended-controls.rst | 7 +++++++
 drivers/media/v4l2-core/v4l2-ctrls.c               | 1 +
 include/uapi/linux/v4l2-controls.h                 | 2 +-
 4 files changed, 15 insertions(+), 1 deletion(-)

-- 
2.7.4

[PATCH v2 1/2] v4l: ctrls: Add a control for digital gain

[Sakari Ailus]

Add V4L2_CID_DIGITAL_GAIN to control explicitly digital gain.

We already have analogue gain control which the digital gain control
complements. Typically higher quality images are obtained using analogue
gain only as the digital gain does not add information to the image
(rather it may remove it).

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 Documentation/media/uapi/v4l/extended-controls.rst | 7 +++++++
 drivers/media/v4l2-core/v4l2-ctrls.c               | 1 +
 include/uapi/linux/v4l2-controls.h                 | 2 +-
 3 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst
index 76c5b1a..9acc9cad 100644
--- a/Documentation/media/uapi/v4l/extended-controls.rst
+++ b/Documentation/media/uapi/v4l/extended-controls.rst
@@ -3021,6 +3021,13 @@ Image Process Control IDs
     The video deinterlacing mode (such as Bob, Weave, ...). The menu items are
     driver specific and are documented in :ref:`v4l-drivers`.
 
+``V4L2_CID_DIGITAL_GAIN (integer)``
+    Digital gain is the value by which all colour components
+    are multiplied by. Typically the digital gain applied is the
+    control value divided by e.g. 0x100, meaning that to get no
+    digital gain the control value needs to be 0x100. The no-gain
+    configuration is also typically the default.
+
 
 .. _dv-controls:
 
diff --git a/drivers/media/v4l2-core/v4l2-ctrls.c b/drivers/media/v4l2-core/v4l2-ctrls.c
index 5aed7bd..36eede3 100644
--- a/drivers/media/v4l2-core/v4l2-ctrls.c
+++ b/drivers/media/v4l2-core/v4l2-ctrls.c
@@ -886,6 +886,7 @@ const char *v4l2_ctrl_get_name(u32 id)
 	case V4L2_CID_PIXEL_RATE:		return "Pixel Rate";
 	case V4L2_CID_TEST_PATTERN:		return "Test Pattern";
 	case V4L2_CID_DEINTERLACING_MODE:	return "Deinterlacing Mode";
+	case V4L2_CID_DIGITAL_GAIN:		return "Digital Gain";
 
 	/* DV controls */
 	/* Keep the order of the 'case's the same as in v4l2-controls.h! */
diff --git a/include/uapi/linux/v4l2-controls.h b/include/uapi/linux/v4l2-controls.h
index 0d2e1e0..0cdb8eb 100644
--- a/include/uapi/linux/v4l2-controls.h
+++ b/include/uapi/linux/v4l2-controls.h
@@ -893,7 +893,7 @@ enum v4l2_jpeg_chroma_subsampling {
 #define V4L2_CID_PIXEL_RATE			(V4L2_CID_IMAGE_PROC_CLASS_BASE + 2)
 #define V4L2_CID_TEST_PATTERN			(V4L2_CID_IMAGE_PROC_CLASS_BASE + 3)
 #define V4L2_CID_DEINTERLACING_MODE		(V4L2_CID_IMAGE_PROC_CLASS_BASE + 4)
-
+#define V4L2_CID_DIGITAL_GAIN			(V4L2_CID_IMAGE_PROC_CLASS_BASE + 5)
 
 /*  DV-class control IDs defined by V4L2 */
 #define V4L2_CID_DV_CLASS_BASE			(V4L2_CTRL_CLASS_DV | 0x900)
-- 
2.7.4

[PATCH v2 2/2] v4l: controls: Improve documentation for V4L2_CID_GAIN

[Sakari Ailus]

Elaborate the differences between V4L2_CID_GAIN and gain-type specific
V4L2_CID_DIGITAL_GAIN and V4L2_CID_ANALOGUE_GAIN.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 Documentation/media/uapi/v4l/control.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst
index 51112ba..c1e6adb 100644
--- a/Documentation/media/uapi/v4l/control.rst
+++ b/Documentation/media/uapi/v4l/control.rst
@@ -137,6 +137,12 @@ Control IDs
 ``V4L2_CID_GAIN`` ``(integer)``
     Gain control.
 
+    Primarily used to control gain on e.g. TV tuners but also on
+    webcams. Most devices control only digital gain with this control
+    but on some this could include analogue gain as well. Devices that
+    recognise the difference between digital and analogue gain use
+    controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``.
+
 ``V4L2_CID_HFLIP`` ``(boolean)``
     Mirror the picture horizontally.
 
-- 
2.7.4

Re: [PATCH v2 1/2] v4l: ctrls: Add a control for digital gain

[Hans Verkuil]

On 06/09/17 15:21, Sakari Ailus wrote:
> Add V4L2_CID_DIGITAL_GAIN to control explicitly digital gain.
> 
> We already have analogue gain control which the digital gain control
> complements. Typically higher quality images are obtained using analogue
> gain only as the digital gain does not add information to the image
> (rather it may remove it).
> 
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>

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

Regards,

	Hans

> ---
>  Documentation/media/uapi/v4l/extended-controls.rst | 7 +++++++
>  drivers/media/v4l2-core/v4l2-ctrls.c               | 1 +
>  include/uapi/linux/v4l2-controls.h                 | 2 +-
>  3 files changed, 9 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst
> index 76c5b1a..9acc9cad 100644
> --- a/Documentation/media/uapi/v4l/extended-controls.rst
> +++ b/Documentation/media/uapi/v4l/extended-controls.rst
> @@ -3021,6 +3021,13 @@ Image Process Control IDs
>      The video deinterlacing mode (such as Bob, Weave, ...). The menu items are
>      driver specific and are documented in :ref:`v4l-drivers`.
>  
> +``V4L2_CID_DIGITAL_GAIN (integer)``
> +    Digital gain is the value by which all colour components
> +    are multiplied by. Typically the digital gain applied is the
> +    control value divided by e.g. 0x100, meaning that to get no
> +    digital gain the control value needs to be 0x100. The no-gain
> +    configuration is also typically the default.
> +
>  
>  .. _dv-controls:
>  
> diff --git a/drivers/media/v4l2-core/v4l2-ctrls.c b/drivers/media/v4l2-core/v4l2-ctrls.c
> index 5aed7bd..36eede3 100644
> --- a/drivers/media/v4l2-core/v4l2-ctrls.c
> +++ b/drivers/media/v4l2-core/v4l2-ctrls.c
> @@ -886,6 +886,7 @@ const char *v4l2_ctrl_get_name(u32 id)
>  	case V4L2_CID_PIXEL_RATE:		return "Pixel Rate";
>  	case V4L2_CID_TEST_PATTERN:		return "Test Pattern";
>  	case V4L2_CID_DEINTERLACING_MODE:	return "Deinterlacing Mode";
> +	case V4L2_CID_DIGITAL_GAIN:		return "Digital Gain";
>  
>  	/* DV controls */
>  	/* Keep the order of the 'case's the same as in v4l2-controls.h! */
> diff --git a/include/uapi/linux/v4l2-controls.h b/include/uapi/linux/v4l2-controls.h
> index 0d2e1e0..0cdb8eb 100644
> --- a/include/uapi/linux/v4l2-controls.h
> +++ b/include/uapi/linux/v4l2-controls.h
> @@ -893,7 +893,7 @@ enum v4l2_jpeg_chroma_subsampling {
>  #define V4L2_CID_PIXEL_RATE			(V4L2_CID_IMAGE_PROC_CLASS_BASE + 2)
>  #define V4L2_CID_TEST_PATTERN			(V4L2_CID_IMAGE_PROC_CLASS_BASE + 3)
>  #define V4L2_CID_DEINTERLACING_MODE		(V4L2_CID_IMAGE_PROC_CLASS_BASE + 4)
> -
> +#define V4L2_CID_DIGITAL_GAIN			(V4L2_CID_IMAGE_PROC_CLASS_BASE + 5)
>  
>  /*  DV-class control IDs defined by V4L2 */
>  #define V4L2_CID_DV_CLASS_BASE			(V4L2_CTRL_CLASS_DV | 0x900)
> 

Re: [PATCH v2 2/2] v4l: controls: Improve documentation for V4L2_CID_GAIN

[Hans Verkuil]

On 06/09/17 15:21, Sakari Ailus wrote:
> Elaborate the differences between V4L2_CID_GAIN and gain-type specific
> V4L2_CID_DIGITAL_GAIN and V4L2_CID_ANALOGUE_GAIN.
> 
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>


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

Regards,

	Hans

> ---
>  Documentation/media/uapi/v4l/control.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst
> index 51112ba..c1e6adb 100644
> --- a/Documentation/media/uapi/v4l/control.rst
> +++ b/Documentation/media/uapi/v4l/control.rst
> @@ -137,6 +137,12 @@ Control IDs
>  ``V4L2_CID_GAIN`` ``(integer)``
>      Gain control.
>  
> +    Primarily used to control gain on e.g. TV tuners but also on
> +    webcams. Most devices control only digital gain with this control
> +    but on some this could include analogue gain as well. Devices that
> +    recognise the difference between digital and analogue gain use
> +    controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``.
> +
>  ``V4L2_CID_HFLIP`` ``(boolean)``
>      Mirror the picture horizontally.
>  
>