Skip to content

Commit 9926c22

Browse files
jmondimchehab
jmondi
authored and
mchehab
committed
media: v4l2-ctrl: Document V4L2_CID_CAMERA_SENSOR_ROTATION
Add documentation for the V4L2_CID_CAMERA_SENSOR_ROTATION camera control. The newly added read-only control reports the rotation correction to be applied to images before displaying them to the user. Signed-off-by: Jacopo Mondi <[email protected]> Signed-off-by: Hans Verkuil <[email protected]> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
1 parent 9397a83 commit 9926c22

File tree

1 file changed

+121
-0
lines changed

1 file changed

+121
-0
lines changed

‎Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -540,6 +540,127 @@ enum v4l2_scene_mode -
540540

541541

542542

543+
``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)``
544+
This read-only control describes the rotation correction in degrees in the
545+
counter-clockwise direction to be applied to the captured images once
546+
captured to memory to compensate for the camera sensor mounting rotation.
547+
548+
For a precise definition of the sensor mounting rotation refer to the
549+
extensive description of the 'rotation' properties in the device tree
550+
bindings file 'video-interfaces.txt'.
551+
552+
A few examples are below reported, using a shark swimming from left to
553+
right in front of the user as the example scene to capture. ::
554+
555+
0 X-axis
556+
0 +------------------------------------->
557+
!
558+
!
559+
!
560+
! |\____)\___
561+
! ) _____ __`<
562+
! |/ )/
563+
!
564+
!
565+
!
566+
V
567+
Y-axis
568+
569+
Example one - Webcam
570+
571+
Assuming you can bring your laptop with you while swimming with sharks,
572+
the camera module of the laptop is installed on the user facing part of a
573+
laptop screen casing, and is typically used for video calls. The captured
574+
images are meant to be displayed in landscape mode (width > height) on the
575+
laptop screen.
576+
577+
The camera is typically mounted upside-down to compensate the lens optical
578+
inversion effect. In this case the value of the
579+
V4L2_CID_CAMERA_SENSOR_ROTATION control is 0, no rotation is required to
580+
display images correctly to the user.
581+
582+
If the camera sensor is not mounted upside-down it is required to compensate
583+
the lens optical inversion effect and the value of the
584+
V4L2_CID_CAMERA_SENSOR_ROTATION control is 180 degrees, as images will
585+
result rotated when captured to memory. ::
586+
587+
+--------------------------------------+
588+
! !
589+
! !
590+
! !
591+
! __/(_____/| !
592+
! >.___ ____ ( !
593+
! \( \| !
594+
! !
595+
! !
596+
! !
597+
+--------------------------------------+
598+
599+
A software rotation correction of 180 degrees has to be applied to correctly
600+
display the image on the user screen. ::
601+
602+
+--------------------------------------+
603+
! !
604+
! !
605+
! !
606+
! |\____)\___ !
607+
! ) _____ __`< !
608+
! |/ )/ !
609+
! !
610+
! !
611+
! !
612+
+--------------------------------------+
613+
614+
Example two - Phone camera
615+
616+
It is more handy to go and swim with sharks with only your mobile phone
617+
with you and take pictures with the camera that is installed on the back
618+
side of the device, facing away from the user. The captured images are meant
619+
to be displayed in portrait mode (height > width) to match the device screen
620+
orientation and the device usage orientation used when taking the picture.
621+
622+
The camera sensor is typically mounted with its pixel array longer side
623+
aligned to the device longer side, upside-down mounted to compensate for
624+
the lens optical inversion effect.
625+
626+
The images once captured to memory will be rotated and the value of the
627+
V4L2_CID_CAMERA_SENSOR_ROTATION will report a 90 degree rotation. ::
628+
629+
630+
+-------------------------------------+
631+
| _ _ |
632+
| \ / |
633+
| | | |
634+
| | | |
635+
| | > |
636+
| < | |
637+
| | | |
638+
| . |
639+
| V |
640+
+-------------------------------------+
641+
642+
A correction of 90 degrees in counter-clockwise direction has to be
643+
applied to correctly display the image in portrait mode on the device
644+
screen. ::
645+
646+
+--------------------+
647+
| |
648+
| |
649+
| |
650+
| |
651+
| |
652+
| |
653+
| |\____)\___ |
654+
| ) _____ __`< |
655+
| |/ )/ |
656+
| |
657+
| |
658+
| |
659+
| |
660+
| |
661+
+--------------------+
662+
663+
543664
.. [#f1]
544665
This control may be changed to a menu control in the future, if more
545666
options are required.

0 commit comments

Comments
 (0)