media: v4l2-ctrl: Document V4L2_CID_CAMERA_SENSOR_ROTATION (9926c224) · Commits · jan.koester / Linux

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

+121 −0

Original line number	Diff line number	Diff line
		@@ -540,6 +540,127 @@ enum v4l2_scene_mode -



		``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)``
		This read-only control describes the rotation correction in degrees in the
		counter-clockwise direction to be applied to the captured images once
		captured to memory to compensate for the camera sensor mounting rotation.

		For a precise definition of the sensor mounting rotation refer to the
		extensive description of the 'rotation' properties in the device tree
		bindings file 'video-interfaces.txt'.

		A few examples are below reported, using a shark swimming from left to
		right in front of the user as the example scene to capture. ::

		0 X-axis
		0 +------------------------------------->
		!
		!
		!
		! \|\____)\___
		! ) _____ __`<
		! \|/ )/
		!
		!
		!
		V
		Y-axis

		Example one - Webcam

		Assuming you can bring your laptop with you while swimming with sharks,
		the camera module of the laptop is installed on the user facing part of a
		laptop screen casing, and is typically used for video calls. The captured
		images are meant to be displayed in landscape mode (width > height) on the
		laptop screen.

		The camera is typically mounted upside-down to compensate the lens optical
		inversion effect. In this case the value of the
		V4L2_CID_CAMERA_SENSOR_ROTATION control is 0, no rotation is required to
		display images correctly to the user.

		If the camera sensor is not mounted upside-down it is required to compensate
		the lens optical inversion effect and the value of the
		V4L2_CID_CAMERA_SENSOR_ROTATION control is 180 degrees, as images will
		result rotated when captured to memory. ::

		+--------------------------------------+
		! !
		! !
		! !
		! __/(_____/\| !
		! >.___ ____ ( !
		! \( \\| !
		! !
		! !
		! !
		+--------------------------------------+

		A software rotation correction of 180 degrees has to be applied to correctly
		display the image on the user screen. ::

		+--------------------------------------+
		! !
		! !
		! !
		! \|\____)\___ !
		! ) _____ __`< !
		! \|/ )/ !
		! !
		! !
		! !
		+--------------------------------------+

		Example two - Phone camera

		It is more handy to go and swim with sharks with only your mobile phone
		with you and take pictures with the camera that is installed on the back
		side of the device, facing away from the user. The captured images are meant
		to be displayed in portrait mode (height > width) to match the device screen
		orientation and the device usage orientation used when taking the picture.

		The camera sensor is typically mounted with its pixel array longer side
		aligned to the device longer side, upside-down mounted to compensate for
		the lens optical inversion effect.

		The images once captured to memory will be rotated and the value of the
		V4L2_CID_CAMERA_SENSOR_ROTATION will report a 90 degree rotation. ::


		+-------------------------------------+
		\| _ _ \|
		\| \ / \|
		\| \| \| \|
		\| \| \| \|
		\| \| > \|
		\| < \| \|
		\| \| \| \|
		\| . \|
		\| V \|
		+-------------------------------------+

		A correction of 90 degrees in counter-clockwise direction has to be
		applied to correctly display the image in portrait mode on the device
		screen. ::

		+--------------------+
		\| \|
		\| \|
		\| \|
		\| \|
		\| \|
		\| \|
		\| \|\____)\___ \|
		\| ) _____ __`< \|
		\| \|/ )/ \|
		\| \|
		\| \|
		\| \|
		\| \|
		\| \|
		+--------------------+


		.. [#f1]
		This control may be changed to a menu control in the future, if more
		options are required.