target/linux/bcm27xx/patches-5.4/950-0905-media-v4l2-ctrl-Document-V4L2_CID_CAMERA_SENSOR_ROTA.patch

   1 From 00d84a43c7042b55e81d0818b0d1a6e44c6f79b5 Mon Sep 17 00:00:00 2001
   2 From: Jacopo Mondi <jacopo@jmondi.org>
   3 Date: Sat, 9 May 2020 11:04:47 +0200
   4 Subject: [PATCH] media: v4l2-ctrl: Document
   5  V4L2_CID_CAMERA_SENSOR_ROTATION
   6
   7 Add documentation for the V4L2_CID_CAMERA_SENSOR_ROTATION camera
   8 control. The newly added read-only control reports the rotation
   9 correction to be applied to images before displaying them to the user.
  10
  11 Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
  12 Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
  13 Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
  14
  15 Commit 9926c2248740a632b0629fd8c07d0fc361dc15cc upstream
  16
  17 Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
  18 ---
  19  .../media/uapi/v4l/ext-ctrls-camera.rst       | 121 ++++++++++++++++++
  20  1 file changed, 121 insertions(+)
  21
  22 --- a/Documentation/media/uapi/v4l/ext-ctrls-camera.rst
  23 +++ b/Documentation/media/uapi/v4l/ext-ctrls-camera.rst
  24 @@ -540,6 +540,127 @@ enum v4l2_scene_mode -
  25
  26
  27
  28 +``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)``
  29 +    This read-only control describes the rotation correction in degrees in the
  30 +    counter-clockwise direction to be applied to the captured images once
  31 +    captured to memory to compensate for the camera sensor mounting rotation.
  32 +
  33 +    For a precise definition of the sensor mounting rotation refer to the
  34 +    extensive description of the 'rotation' properties in the device tree
  35 +    bindings file 'video-interfaces.txt'.
  36 +
  37 +    A few examples are below reported, using a shark swimming from left to
  38 +    right in front of the user as the example scene to capture. ::
  39 +
  40 +                 0               X-axis
  41 +               0 +------------------------------------->
  42 +                 !
  43 +                 !
  44 +                 !
  45 +                 !           |\____)\___
  46 +                 !           ) _____  __`<
  47 +                 !           |/     )/
  48 +                 !
  49 +                 !
  50 +                 !
  51 +                 V
  52 +               Y-axis
  53 +
  54 +    Example one - Webcam
  55 +
  56 +    Assuming you can bring your laptop with you while swimming with sharks,
  57 +    the camera module of the laptop is installed on the user facing part of a
  58 +    laptop screen casing, and is typically used for video calls. The captured
  59 +    images are meant to be displayed in landscape mode (width > height) on the
  60 +    laptop screen.
  61 +
  62 +    The camera is typically mounted upside-down to compensate the lens optical
  63 +    inversion effect. In this case the value of the
  64 +    V4L2_CID_CAMERA_SENSOR_ROTATION control is 0, no rotation is required to
  65 +    display images correctly to the user.
  66 +
  67 +    If the camera sensor is not mounted upside-down it is required to compensate
  68 +    the lens optical inversion effect and the value of the
  69 +    V4L2_CID_CAMERA_SENSOR_ROTATION control is 180 degrees, as images will
  70 +    result rotated when captured to memory. ::
  71 +
  72 +                 +--------------------------------------+
  73 +                 !                                      !
  74 +                 !                                      !
  75 +                 !                                      !
  76 +                 !              __/(_____/|             !
  77 +                 !            >.___  ____ (             !
  78 +                 !                 \(    \|             !
  79 +                 !                                      !
  80 +                 !                                      !
  81 +                 !                                      !
  82 +                 +--------------------------------------+
  83 +
  84 +    A software rotation correction of 180 degrees has to be applied to correctly
  85 +    display the image on the user screen. ::
  86 +
  87 +                 +--------------------------------------+
  88 +                 !                                      !
  89 +                 !                                      !
  90 +                 !                                      !
  91 +                 !             |\____)\___              !
  92 +                 !             ) _____  __`<            !
  93 +                 !             |/     )/                !
  94 +                 !                                      !
  95 +                 !                                      !
  96 +                 !                                      !
  97 +                 +--------------------------------------+
  98 +
  99 +    Example two - Phone camera
 100 +
 101 +    It is more handy to go and swim with sharks with only your mobile phone
 102 +    with you and take pictures with the camera that is installed on the back
 103 +    side of the device, facing away from the user. The captured images are meant
 104 +    to be displayed in portrait mode (height > width) to match the device screen
 105 +    orientation and the device usage orientation used when taking the picture.
 106 +
 107 +    The camera sensor is typically mounted with its pixel array longer side
 108 +    aligned to the device longer side, upside-down mounted to compensate for
 109 +    the lens optical inversion effect.
 110 +
 111 +    The images once captured to memory will be rotated and the value of the
 112 +    V4L2_CID_CAMERA_SENSOR_ROTATION will report a 90 degree rotation. ::
 113 +
 114 +
 115 +                 +-------------------------------------+
 116 +                 |                 _ _                 |
 117 +                 |                \   /                |
 118 +                 |                 | |                 |
 119 +                 |                 | |                 |
 120 +                 |                 |  >                |
 121 +                 |                <  |                 |
 122 +                 |                 | |                 |
 123 +                 |                   .                 |
 124 +                 |                  V                  |
 125 +                 +-------------------------------------+
 126 +
 127 +    A correction of 90 degrees in counter-clockwise direction has to be
 128 +    applied to correctly display the image in portrait mode on the device
 129 +    screen. ::
 130 +
 131 +                          +--------------------+
 132 +                          |                    |
 133 +                          |                    |
 134 +                          |                    |
 135 +                          |                    |
 136 +                          |                    |
 137 +                          |                    |
 138 +                          |   |\____)\___      |
 139 +                          |   ) _____  __`<    |
 140 +                          |   |/     )/        |
 141 +                          |                    |
 142 +                          |                    |
 143 +                          |                    |
 144 +                          |                    |
 145 +                          |                    |
 146 +                          +--------------------+
 147 +
 148 +
 149  .. [#f1]
 150     This control may be changed to a menu control in the future, if more
 151     options are required.