141f42b6eSRob Herring# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) 241f42b6eSRob Herring%YAML 1.2 341f42b6eSRob Herring--- 441f42b6eSRob Herring$id: http://devicetree.org/schemas/media/video-interface-devices.yaml# 541f42b6eSRob Herring$schema: http://devicetree.org/meta-schemas/core.yaml# 641f42b6eSRob Herring 7*ab040c42SKrzysztof Kozlowskititle: Common Properties for Video Receiver and Transmitter Devices 841f42b6eSRob Herring 941f42b6eSRob Herringmaintainers: 1041f42b6eSRob Herring - Jacopo Mondi <jacopo@jmondi.org> 1141f42b6eSRob Herring - Sakari Ailus <sakari.ailus@linux.intel.com> 1241f42b6eSRob Herring 1341f42b6eSRob Herringproperties: 1441f42b6eSRob Herring flash-leds: 1541f42b6eSRob Herring $ref: /schemas/types.yaml#/definitions/phandle-array 1641f42b6eSRob Herring description: 1741f42b6eSRob Herring An array of phandles, each referring to a flash LED, a sub-node of the LED 1841f42b6eSRob Herring driver device node. 1941f42b6eSRob Herring 2041f42b6eSRob Herring lens-focus: 2141f42b6eSRob Herring $ref: /schemas/types.yaml#/definitions/phandle 2241f42b6eSRob Herring description: 2341f42b6eSRob Herring A phandle to the node of the focus lens controller. 2441f42b6eSRob Herring 2541f42b6eSRob Herring rotation: 2641f42b6eSRob Herring $ref: /schemas/types.yaml#/definitions/uint32 2741f42b6eSRob Herring enum: [ 0, 90, 180, 270 ] 2841f42b6eSRob Herring description: | 2941f42b6eSRob Herring The camera rotation is expressed as the angular difference in degrees 3041f42b6eSRob Herring between two reference systems, one relative to the camera module, and one 3141f42b6eSRob Herring defined on the external world scene to be captured when projected on the 3241f42b6eSRob Herring image sensor pixel array. 3341f42b6eSRob Herring 3441f42b6eSRob Herring A camera sensor has a 2-dimensional reference system 'Rc' defined by its 3541f42b6eSRob Herring pixel array read-out order. The origin is set to the first pixel being 3641f42b6eSRob Herring read out, the X-axis points along the column read-out direction towards 3741f42b6eSRob Herring the last columns, and the Y-axis along the row read-out direction towards 3841f42b6eSRob Herring the last row. 3941f42b6eSRob Herring 4041f42b6eSRob Herring A typical example for a sensor with a 2592x1944 pixel array matrix 4141f42b6eSRob Herring observed from the front is: 4241f42b6eSRob Herring 4341f42b6eSRob Herring 2591 X-axis 0 4441f42b6eSRob Herring <------------------------+ 0 4541f42b6eSRob Herring .......... ... ..........! 4641f42b6eSRob Herring .......... ... ..........! Y-axis 4741f42b6eSRob Herring ... ! 4841f42b6eSRob Herring .......... ... ..........! 4941f42b6eSRob Herring .......... ... ..........! 1943 5041f42b6eSRob Herring V 5141f42b6eSRob Herring 5241f42b6eSRob Herring The external world scene reference system 'Rs' is a 2-dimensional 5341f42b6eSRob Herring reference system on the focal plane of the camera module. The origin is 5441f42b6eSRob Herring placed on the top-left corner of the visible scene, the X-axis points 5541f42b6eSRob Herring towards the right, and the Y-axis points towards the bottom of the scene. 5641f42b6eSRob Herring The top, bottom, left and right directions are intentionally not defined 5741f42b6eSRob Herring and depend on the environment in which the camera is used. 5841f42b6eSRob Herring 5941f42b6eSRob Herring A typical example of a (very common) picture of a shark swimming from left 6041f42b6eSRob Herring to right, as seen from the camera, is: 6141f42b6eSRob Herring 6241f42b6eSRob Herring 0 X-axis 6341f42b6eSRob Herring 0 +-------------------------------------> 6441f42b6eSRob Herring ! 6541f42b6eSRob Herring ! 6641f42b6eSRob Herring ! 6741f42b6eSRob Herring ! |\____)\___ 6841f42b6eSRob Herring ! ) _____ __`< 6941f42b6eSRob Herring ! |/ )/ 7041f42b6eSRob Herring ! 7141f42b6eSRob Herring ! 7241f42b6eSRob Herring ! 7341f42b6eSRob Herring V 7441f42b6eSRob Herring Y-axis 7541f42b6eSRob Herring 7641f42b6eSRob Herring with the reference system 'Rs' placed on the camera focal plane: 7741f42b6eSRob Herring 7841f42b6eSRob Herring ¸.·˙! 7941f42b6eSRob Herring ¸.·˙ ! 8041f42b6eSRob Herring _ ¸.·˙ ! 8141f42b6eSRob Herring +-/ \-+¸.·˙ ! 8241f42b6eSRob Herring | (o) | ! Camera focal plane 8341f42b6eSRob Herring +-----+˙·.¸ ! 8441f42b6eSRob Herring ˙·.¸ ! 8541f42b6eSRob Herring ˙·.¸ ! 8641f42b6eSRob Herring ˙·.¸! 8741f42b6eSRob Herring 8841f42b6eSRob Herring When projected on the sensor's pixel array, the image and the associated 8941f42b6eSRob Herring reference system 'Rs' are typically (but not always) inverted, due to the 9041f42b6eSRob Herring camera module's lens optical inversion effect. 9141f42b6eSRob Herring 9241f42b6eSRob Herring Assuming the above represented scene of the swimming shark, the lens 9341f42b6eSRob Herring inversion projects the scene and its reference system onto the sensor 9441f42b6eSRob Herring pixel array, seen from the front of the camera sensor, as follows: 9541f42b6eSRob Herring 9641f42b6eSRob Herring Y-axis 9741f42b6eSRob Herring ^ 9841f42b6eSRob Herring ! 9941f42b6eSRob Herring ! 10041f42b6eSRob Herring ! 10141f42b6eSRob Herring ! |\_____)\__ 10241f42b6eSRob Herring ! ) ____ ___.< 10341f42b6eSRob Herring ! |/ )/ 10441f42b6eSRob Herring ! 10541f42b6eSRob Herring ! 10641f42b6eSRob Herring ! 10741f42b6eSRob Herring 0 +-------------------------------------> 10841f42b6eSRob Herring 0 X-axis 10941f42b6eSRob Herring 11041f42b6eSRob Herring Note the shark being upside-down. 11141f42b6eSRob Herring 11241f42b6eSRob Herring The resulting projected reference system is named 'Rp'. 11341f42b6eSRob Herring 11441f42b6eSRob Herring The camera rotation property is then defined as the angular difference in 11541f42b6eSRob Herring the counter-clockwise direction between the camera reference system 'Rc' 11641f42b6eSRob Herring and the projected scene reference system 'Rp'. It is expressed in degrees 11741f42b6eSRob Herring as a number in the range [0, 360[. 11841f42b6eSRob Herring 11941f42b6eSRob Herring Examples 12041f42b6eSRob Herring 12141f42b6eSRob Herring 0 degrees camera rotation: 12241f42b6eSRob Herring 12341f42b6eSRob Herring 12441f42b6eSRob Herring Y-Rp 12541f42b6eSRob Herring ^ 12641f42b6eSRob Herring Y-Rc ! 12741f42b6eSRob Herring ^ ! 12841f42b6eSRob Herring ! ! 12941f42b6eSRob Herring ! ! 13041f42b6eSRob Herring ! ! 13141f42b6eSRob Herring ! ! 13241f42b6eSRob Herring ! ! 13341f42b6eSRob Herring ! ! 13441f42b6eSRob Herring ! ! 13541f42b6eSRob Herring ! 0 +-------------------------------------> 13641f42b6eSRob Herring ! 0 X-Rp 13741f42b6eSRob Herring 0 +-------------------------------------> 13841f42b6eSRob Herring 0 X-Rc 13941f42b6eSRob Herring 14041f42b6eSRob Herring 14141f42b6eSRob Herring X-Rc 0 14241f42b6eSRob Herring <------------------------------------+ 0 14341f42b6eSRob Herring X-Rp 0 ! 14441f42b6eSRob Herring <------------------------------------+ 0 ! 14541f42b6eSRob Herring ! ! 14641f42b6eSRob Herring ! ! 14741f42b6eSRob Herring ! ! 14841f42b6eSRob Herring ! ! 14941f42b6eSRob Herring ! ! 15041f42b6eSRob Herring ! ! 15141f42b6eSRob Herring ! ! 15241f42b6eSRob Herring ! V 15341f42b6eSRob Herring ! Y-Rc 15441f42b6eSRob Herring V 15541f42b6eSRob Herring Y-Rp 15641f42b6eSRob Herring 15741f42b6eSRob Herring 90 degrees camera rotation: 15841f42b6eSRob Herring 15941f42b6eSRob Herring 0 Y-Rc 16041f42b6eSRob Herring 0 +--------------------> 16141f42b6eSRob Herring ! Y-Rp 16241f42b6eSRob Herring ! ^ 16341f42b6eSRob Herring ! ! 16441f42b6eSRob Herring ! ! 16541f42b6eSRob Herring ! ! 16641f42b6eSRob Herring ! ! 16741f42b6eSRob Herring ! ! 16841f42b6eSRob Herring ! ! 16941f42b6eSRob Herring ! ! 17041f42b6eSRob Herring ! ! 17141f42b6eSRob Herring ! ! 17241f42b6eSRob Herring ! 0 +-------------------------------------> 17341f42b6eSRob Herring ! 0 X-Rp 17441f42b6eSRob Herring ! 17541f42b6eSRob Herring ! 17641f42b6eSRob Herring ! 17741f42b6eSRob Herring ! 17841f42b6eSRob Herring V 17941f42b6eSRob Herring X-Rc 18041f42b6eSRob Herring 18141f42b6eSRob Herring 180 degrees camera rotation: 18241f42b6eSRob Herring 18341f42b6eSRob Herring 0 18441f42b6eSRob Herring <------------------------------------+ 0 18541f42b6eSRob Herring X-Rc ! 18641f42b6eSRob Herring Y-Rp ! 18741f42b6eSRob Herring ^ ! 18841f42b6eSRob Herring ! ! 18941f42b6eSRob Herring ! ! 19041f42b6eSRob Herring ! ! 19141f42b6eSRob Herring ! ! 19241f42b6eSRob Herring ! ! 19341f42b6eSRob Herring ! ! 19441f42b6eSRob Herring ! V 19541f42b6eSRob Herring ! Y-Rc 19641f42b6eSRob Herring 0 +-------------------------------------> 19741f42b6eSRob Herring 0 X-Rp 19841f42b6eSRob Herring 19941f42b6eSRob Herring 270 degrees camera rotation: 20041f42b6eSRob Herring 20141f42b6eSRob Herring 0 Y-Rc 20241f42b6eSRob Herring 0 +--------------------> 20341f42b6eSRob Herring ! 0 20441f42b6eSRob Herring ! <-----------------------------------+ 0 20541f42b6eSRob Herring ! X-Rp ! 20641f42b6eSRob Herring ! ! 20741f42b6eSRob Herring ! ! 20841f42b6eSRob Herring ! ! 20941f42b6eSRob Herring ! ! 21041f42b6eSRob Herring ! ! 21141f42b6eSRob Herring ! ! 21241f42b6eSRob Herring ! ! 21341f42b6eSRob Herring ! ! 21441f42b6eSRob Herring ! V 21541f42b6eSRob Herring ! Y-Rp 21641f42b6eSRob Herring ! 21741f42b6eSRob Herring ! 21841f42b6eSRob Herring ! 21941f42b6eSRob Herring ! 22041f42b6eSRob Herring V 22141f42b6eSRob Herring X-Rc 22241f42b6eSRob Herring 22341f42b6eSRob Herring 22441f42b6eSRob Herring Example one - Webcam 22541f42b6eSRob Herring 22641f42b6eSRob Herring A camera module installed on the user facing part of a laptop screen 22741f42b6eSRob Herring casing used for video calls. The captured images are meant to be displayed 22841f42b6eSRob Herring in landscape mode (width > height) on the laptop screen. 22941f42b6eSRob Herring 23041f42b6eSRob Herring The camera is typically mounted upside-down to compensate the lens optical 23141f42b6eSRob Herring inversion effect: 23241f42b6eSRob Herring 23341f42b6eSRob Herring Y-Rp 23441f42b6eSRob Herring Y-Rc ^ 23541f42b6eSRob Herring ^ ! 23641f42b6eSRob Herring ! ! 23741f42b6eSRob Herring ! ! |\_____)\__ 23841f42b6eSRob Herring ! ! ) ____ ___.< 23941f42b6eSRob Herring ! ! |/ )/ 24041f42b6eSRob Herring ! ! 24141f42b6eSRob Herring ! ! 24241f42b6eSRob Herring ! ! 24341f42b6eSRob Herring ! 0 +-------------------------------------> 24441f42b6eSRob Herring ! 0 X-Rp 24541f42b6eSRob Herring 0 +-------------------------------------> 24641f42b6eSRob Herring 0 X-Rc 24741f42b6eSRob Herring 24841f42b6eSRob Herring The two reference systems are aligned, the resulting camera rotation is 24941f42b6eSRob Herring 0 degrees, no rotation correction needs to be applied to the resulting 25041f42b6eSRob Herring image once captured to memory buffers to correctly display it to users: 25141f42b6eSRob Herring 25241f42b6eSRob Herring +--------------------------------------+ 25341f42b6eSRob Herring ! ! 25441f42b6eSRob Herring ! ! 25541f42b6eSRob Herring ! ! 25641f42b6eSRob Herring ! |\____)\___ ! 25741f42b6eSRob Herring ! ) _____ __`< ! 25841f42b6eSRob Herring ! |/ )/ ! 25941f42b6eSRob Herring ! ! 26041f42b6eSRob Herring ! ! 26141f42b6eSRob Herring ! ! 26241f42b6eSRob Herring +--------------------------------------+ 26341f42b6eSRob Herring 26441f42b6eSRob Herring If the camera sensor is not mounted upside-down to compensate for the lens 26541f42b6eSRob Herring optical inversion, the two reference systems will not be aligned, with 26641f42b6eSRob Herring 'Rp' being rotated 180 degrees relatively to 'Rc': 26741f42b6eSRob Herring 26841f42b6eSRob Herring 26941f42b6eSRob Herring X-Rc 0 27041f42b6eSRob Herring <------------------------------------+ 0 27141f42b6eSRob Herring ! 27241f42b6eSRob Herring Y-Rp ! 27341f42b6eSRob Herring ^ ! 27441f42b6eSRob Herring ! ! 27541f42b6eSRob Herring ! |\_____)\__ ! 27641f42b6eSRob Herring ! ) ____ ___.< ! 27741f42b6eSRob Herring ! |/ )/ ! 27841f42b6eSRob Herring ! ! 27941f42b6eSRob Herring ! ! 28041f42b6eSRob Herring ! V 28141f42b6eSRob Herring ! Y-Rc 28241f42b6eSRob Herring 0 +-------------------------------------> 28341f42b6eSRob Herring 0 X-Rp 28441f42b6eSRob Herring 28541f42b6eSRob Herring The image once captured to memory will then be rotated by 180 degrees: 28641f42b6eSRob Herring 28741f42b6eSRob Herring +--------------------------------------+ 28841f42b6eSRob Herring ! ! 28941f42b6eSRob Herring ! ! 29041f42b6eSRob Herring ! ! 29141f42b6eSRob Herring ! __/(_____/| ! 29241f42b6eSRob Herring ! >.___ ____ ( ! 29341f42b6eSRob Herring ! \( \| ! 29441f42b6eSRob Herring ! ! 29541f42b6eSRob Herring ! ! 29641f42b6eSRob Herring ! ! 29741f42b6eSRob Herring +--------------------------------------+ 29841f42b6eSRob Herring 29941f42b6eSRob Herring A software rotation correction of 180 degrees should be applied to 30041f42b6eSRob Herring correctly display the image: 30141f42b6eSRob Herring 30241f42b6eSRob Herring +--------------------------------------+ 30341f42b6eSRob Herring ! ! 30441f42b6eSRob Herring ! ! 30541f42b6eSRob Herring ! ! 30641f42b6eSRob Herring ! |\____)\___ ! 30741f42b6eSRob Herring ! ) _____ __`< ! 30841f42b6eSRob Herring ! |/ )/ ! 30941f42b6eSRob Herring ! ! 31041f42b6eSRob Herring ! ! 31141f42b6eSRob Herring ! ! 31241f42b6eSRob Herring +--------------------------------------+ 31341f42b6eSRob Herring 31441f42b6eSRob Herring Example two - Phone camera 31541f42b6eSRob Herring 31641f42b6eSRob Herring A camera installed on the back side of a mobile device facing away from 31741f42b6eSRob Herring the user. The captured images are meant to be displayed in portrait mode 31841f42b6eSRob Herring (height > width) to match the device screen orientation and the device 31941f42b6eSRob Herring usage orientation used when taking the picture. 32041f42b6eSRob Herring 32141f42b6eSRob Herring The camera sensor is typically mounted with its pixel array longer side 32241f42b6eSRob Herring aligned to the device longer side, upside-down mounted to compensate for 32341f42b6eSRob Herring the lens optical inversion effect: 32441f42b6eSRob Herring 32541f42b6eSRob Herring 0 Y-Rc 32641f42b6eSRob Herring 0 +--------------------> 32741f42b6eSRob Herring ! Y-Rp 32841f42b6eSRob Herring ! ^ 32941f42b6eSRob Herring ! ! 33041f42b6eSRob Herring ! ! 33141f42b6eSRob Herring ! ! 33241f42b6eSRob Herring ! ! |\_____)\__ 33341f42b6eSRob Herring ! ! ) ____ ___.< 33441f42b6eSRob Herring ! ! |/ )/ 33541f42b6eSRob Herring ! ! 33641f42b6eSRob Herring ! ! 33741f42b6eSRob Herring ! ! 33841f42b6eSRob Herring ! 0 +-------------------------------------> 33941f42b6eSRob Herring ! 0 X-Rp 34041f42b6eSRob Herring ! 34141f42b6eSRob Herring ! 34241f42b6eSRob Herring ! 34341f42b6eSRob Herring ! 34441f42b6eSRob Herring V 34541f42b6eSRob Herring X-Rc 34641f42b6eSRob Herring 34741f42b6eSRob Herring The two reference systems are not aligned and the 'Rp' reference system is 34841f42b6eSRob Herring rotated by 90 degrees in the counter-clockwise direction relatively to the 34941f42b6eSRob Herring 'Rc' reference system. 35041f42b6eSRob Herring 35141f42b6eSRob Herring The image once captured to memory will be rotated: 35241f42b6eSRob Herring 35341f42b6eSRob Herring +-------------------------------------+ 35441f42b6eSRob Herring | _ _ | 35541f42b6eSRob Herring | \ / | 35641f42b6eSRob Herring | | | | 35741f42b6eSRob Herring | | | | 35841f42b6eSRob Herring | | > | 35941f42b6eSRob Herring | < | | 36041f42b6eSRob Herring | | | | 36141f42b6eSRob Herring | . | 36241f42b6eSRob Herring | V | 36341f42b6eSRob Herring +-------------------------------------+ 36441f42b6eSRob Herring 36541f42b6eSRob Herring A correction of 90 degrees in counter-clockwise direction has to be 36641f42b6eSRob Herring applied to correctly display the image in portrait mode on the device 36741f42b6eSRob Herring screen: 36841f42b6eSRob Herring 36941f42b6eSRob Herring +--------------------+ 37041f42b6eSRob Herring | | 37141f42b6eSRob Herring | | 37241f42b6eSRob Herring | | 37341f42b6eSRob Herring | | 37441f42b6eSRob Herring | | 37541f42b6eSRob Herring | | 37641f42b6eSRob Herring | |\____)\___ | 37741f42b6eSRob Herring | ) _____ __`< | 37841f42b6eSRob Herring | |/ )/ | 37941f42b6eSRob Herring | | 38041f42b6eSRob Herring | | 38141f42b6eSRob Herring | | 38241f42b6eSRob Herring | | 38341f42b6eSRob Herring | | 38441f42b6eSRob Herring +--------------------+ 38541f42b6eSRob Herring 38641f42b6eSRob Herring orientation: 38741f42b6eSRob Herring description: 38841f42b6eSRob Herring The orientation of a device (typically an image sensor or a flash LED) 38941f42b6eSRob Herring describing its mounting position relative to the usage orientation of the 39041f42b6eSRob Herring system where the device is installed on. 39141f42b6eSRob Herring $ref: /schemas/types.yaml#/definitions/uint32 39241f42b6eSRob Herring enum: 39341f42b6eSRob Herring # Front. The device is mounted on the front facing side of the system. For 39441f42b6eSRob Herring # mobile devices such as smartphones, tablets and laptops the front side 39541f42b6eSRob Herring # is the user facing side. 39641f42b6eSRob Herring - 0 39741f42b6eSRob Herring # Back. The device is mounted on the back side of the system, which is 39841f42b6eSRob Herring # defined as the opposite side of the front facing one. 39941f42b6eSRob Herring - 1 40041f42b6eSRob Herring # External. The device is not attached directly to the system but is 40141f42b6eSRob Herring # attached in a way that allows it to move freely. 40241f42b6eSRob Herring - 2 40341f42b6eSRob Herring 40441f42b6eSRob HerringadditionalProperties: true 40541f42b6eSRob Herring 40641f42b6eSRob Herring... 407