0001 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
0002 %YAML 1.2
0003 ---
0004 $id: http://devicetree.org/schemas/media/video-interface-devices.yaml#
0005 $schema: http://devicetree.org/meta-schemas/core.yaml#
0006
0007 title: Common bindings for video receiver and transmitter devices
0008
0009 maintainers:
0010 - Jacopo Mondi <jacopo@jmondi.org>
0011 - Sakari Ailus <sakari.ailus@linux.intel.com>
0012
0013 properties:
0014 flash-leds:
0015 $ref: /schemas/types.yaml#/definitions/phandle-array
0016 description:
0017 An array of phandles, each referring to a flash LED, a sub-node of the LED
0018 driver device node.
0019
0020 lens-focus:
0021 $ref: /schemas/types.yaml#/definitions/phandle
0022 description:
0023 A phandle to the node of the focus lens controller.
0024
0025 rotation:
0026 $ref: /schemas/types.yaml#/definitions/uint32
0027 enum: [ 0, 90, 180, 270 ]
0028 description: |
0029 The camera rotation is expressed as the angular difference in degrees
0030 between two reference systems, one relative to the camera module, and one
0031 defined on the external world scene to be captured when projected on the
0032 image sensor pixel array.
0033
0034 A camera sensor has a 2-dimensional reference system 'Rc' defined by its
0035 pixel array read-out order. The origin is set to the first pixel being
0036 read out, the X-axis points along the column read-out direction towards
0037 the last columns, and the Y-axis along the row read-out direction towards
0038 the last row.
0039
0040 A typical example for a sensor with a 2592x1944 pixel array matrix
0041 observed from the front is:
0042
0043 2591 X-axis 0
0044 <------------------------+ 0
0045 .......... ... ..........!
0046 .......... ... ..........! Y-axis
0047 ... !
0048 .......... ... ..........!
0049 .......... ... ..........! 1943
0050 V
0051
0052 The external world scene reference system 'Rs' is a 2-dimensional
0053 reference system on the focal plane of the camera module. The origin is
0054 placed on the top-left corner of the visible scene, the X-axis points
0055 towards the right, and the Y-axis points towards the bottom of the scene.
0056 The top, bottom, left and right directions are intentionally not defined
0057 and depend on the environment in which the camera is used.
0058
0059 A typical example of a (very common) picture of a shark swimming from left
0060 to right, as seen from the camera, is:
0061
0062 0 X-axis
0063 0 +------------------------------------->
0064 !
0065 !
0066 !
0067 ! |\____)\___
0068 ! ) _____ __`<
0069 ! |/ )/
0070 !
0071 !
0072 !
0073 V
0074 Y-axis
0075
0076 with the reference system 'Rs' placed on the camera focal plane:
0077
0078 ¸.·˙!
0079 ¸.·˙ !
0080 _ ¸.·˙ !
0081 +-/ \-+¸.·˙ !
0082 | (o) | ! Camera focal plane
0083 +-----+˙·.¸ !
0084 ˙·.¸ !
0085 ˙·.¸ !
0086 ˙·.¸!
0087
0088 When projected on the sensor's pixel array, the image and the associated
0089 reference system 'Rs' are typically (but not always) inverted, due to the
0090 camera module's lens optical inversion effect.
0091
0092 Assuming the above represented scene of the swimming shark, the lens
0093 inversion projects the scene and its reference system onto the sensor
0094 pixel array, seen from the front of the camera sensor, as follows:
0095
0096 Y-axis
0097 ^
0098 !
0099 !
0100 !
0101 ! |\_____)\__
0102 ! ) ____ ___.<
0103 ! |/ )/
0104 !
0105 !
0106 !
0107 0 +------------------------------------->
0108 0 X-axis
0109
0110 Note the shark being upside-down.
0111
0112 The resulting projected reference system is named 'Rp'.
0113
0114 The camera rotation property is then defined as the angular difference in
0115 the counter-clockwise direction between the camera reference system 'Rc'
0116 and the projected scene reference system 'Rp'. It is expressed in degrees
0117 as a number in the range [0, 360[.
0118
0119 Examples
0120
0121 0 degrees camera rotation:
0122
0123
0124 Y-Rp
0125 ^
0126 Y-Rc !
0127 ^ !
0128 ! !
0129 ! !
0130 ! !
0131 ! !
0132 ! !
0133 ! !
0134 ! !
0135 ! 0 +------------------------------------->
0136 ! 0 X-Rp
0137 0 +------------------------------------->
0138 0 X-Rc
0139
0140
0141 X-Rc 0
0142 <------------------------------------+ 0
0143 X-Rp 0 !
0144 <------------------------------------+ 0 !
0145 ! !
0146 ! !
0147 ! !
0148 ! !
0149 ! !
0150 ! !
0151 ! !
0152 ! V
0153 ! Y-Rc
0154 V
0155 Y-Rp
0156
0157 90 degrees camera rotation:
0158
0159 0 Y-Rc
0160 0 +-------------------->
0161 ! Y-Rp
0162 ! ^
0163 ! !
0164 ! !
0165 ! !
0166 ! !
0167 ! !
0168 ! !
0169 ! !
0170 ! !
0171 ! !
0172 ! 0 +------------------------------------->
0173 ! 0 X-Rp
0174 !
0175 !
0176 !
0177 !
0178 V
0179 X-Rc
0180
0181 180 degrees camera rotation:
0182
0183 0
0184 <------------------------------------+ 0
0185 X-Rc !
0186 Y-Rp !
0187 ^ !
0188 ! !
0189 ! !
0190 ! !
0191 ! !
0192 ! !
0193 ! !
0194 ! V
0195 ! Y-Rc
0196 0 +------------------------------------->
0197 0 X-Rp
0198
0199 270 degrees camera rotation:
0200
0201 0 Y-Rc
0202 0 +-------------------->
0203 ! 0
0204 ! <-----------------------------------+ 0
0205 ! X-Rp !
0206 ! !
0207 ! !
0208 ! !
0209 ! !
0210 ! !
0211 ! !
0212 ! !
0213 ! !
0214 ! V
0215 ! Y-Rp
0216 !
0217 !
0218 !
0219 !
0220 V
0221 X-Rc
0222
0223
0224 Example one - Webcam
0225
0226 A camera module installed on the user facing part of a laptop screen
0227 casing used for video calls. The captured images are meant to be displayed
0228 in landscape mode (width > height) on the laptop screen.
0229
0230 The camera is typically mounted upside-down to compensate the lens optical
0231 inversion effect:
0232
0233 Y-Rp
0234 Y-Rc ^
0235 ^ !
0236 ! !
0237 ! ! |\_____)\__
0238 ! ! ) ____ ___.<
0239 ! ! |/ )/
0240 ! !
0241 ! !
0242 ! !
0243 ! 0 +------------------------------------->
0244 ! 0 X-Rp
0245 0 +------------------------------------->
0246 0 X-Rc
0247
0248 The two reference systems are aligned, the resulting camera rotation is
0249 0 degrees, no rotation correction needs to be applied to the resulting
0250 image once captured to memory buffers to correctly display it to users:
0251
0252 +--------------------------------------+
0253 ! !
0254 ! !
0255 ! !
0256 ! |\____)\___ !
0257 ! ) _____ __`< !
0258 ! |/ )/ !
0259 ! !
0260 ! !
0261 ! !
0262 +--------------------------------------+
0263
0264 If the camera sensor is not mounted upside-down to compensate for the lens
0265 optical inversion, the two reference systems will not be aligned, with
0266 'Rp' being rotated 180 degrees relatively to 'Rc':
0267
0268
0269 X-Rc 0
0270 <------------------------------------+ 0
0271 !
0272 Y-Rp !
0273 ^ !
0274 ! !
0275 ! |\_____)\__ !
0276 ! ) ____ ___.< !
0277 ! |/ )/ !
0278 ! !
0279 ! !
0280 ! V
0281 ! Y-Rc
0282 0 +------------------------------------->
0283 0 X-Rp
0284
0285 The image once captured to memory will then be rotated by 180 degrees:
0286
0287 +--------------------------------------+
0288 ! !
0289 ! !
0290 ! !
0291 ! __/(_____/| !
0292 ! >.___ ____ ( !
0293 ! \( \| !
0294 ! !
0295 ! !
0296 ! !
0297 +--------------------------------------+
0298
0299 A software rotation correction of 180 degrees should be applied to
0300 correctly display the image:
0301
0302 +--------------------------------------+
0303 ! !
0304 ! !
0305 ! !
0306 ! |\____)\___ !
0307 ! ) _____ __`< !
0308 ! |/ )/ !
0309 ! !
0310 ! !
0311 ! !
0312 +--------------------------------------+
0313
0314 Example two - Phone camera
0315
0316 A camera installed on the back side of a mobile device facing away from
0317 the user. The captured images are meant to be displayed in portrait mode
0318 (height > width) to match the device screen orientation and the device
0319 usage orientation used when taking the picture.
0320
0321 The camera sensor is typically mounted with its pixel array longer side
0322 aligned to the device longer side, upside-down mounted to compensate for
0323 the lens optical inversion effect:
0324
0325 0 Y-Rc
0326 0 +-------------------->
0327 ! Y-Rp
0328 ! ^
0329 ! !
0330 ! !
0331 ! !
0332 ! ! |\_____)\__
0333 ! ! ) ____ ___.<
0334 ! ! |/ )/
0335 ! !
0336 ! !
0337 ! !
0338 ! 0 +------------------------------------->
0339 ! 0 X-Rp
0340 !
0341 !
0342 !
0343 !
0344 V
0345 X-Rc
0346
0347 The two reference systems are not aligned and the 'Rp' reference system is
0348 rotated by 90 degrees in the counter-clockwise direction relatively to the
0349 'Rc' reference system.
0350
0351 The image once captured to memory will be rotated:
0352
0353 +-------------------------------------+
0354 | _ _ |
0355 | \ / |
0356 | | | |
0357 | | | |
0358 | | > |
0359 | < | |
0360 | | | |
0361 | . |
0362 | V |
0363 +-------------------------------------+
0364
0365 A correction of 90 degrees in counter-clockwise direction has to be
0366 applied to correctly display the image in portrait mode on the device
0367 screen:
0368
0369 +--------------------+
0370 | |
0371 | |
0372 | |
0373 | |
0374 | |
0375 | |
0376 | |\____)\___ |
0377 | ) _____ __`< |
0378 | |/ )/ |
0379 | |
0380 | |
0381 | |
0382 | |
0383 | |
0384 +--------------------+
0385
0386 orientation:
0387 description:
0388 The orientation of a device (typically an image sensor or a flash LED)
0389 describing its mounting position relative to the usage orientation of the
0390 system where the device is installed on.
0391 $ref: /schemas/types.yaml#/definitions/uint32
0392 enum:
0393 # Front. The device is mounted on the front facing side of the system. For
0394 # mobile devices such as smartphones, tablets and laptops the front side
0395 # is the user facing side.
0396 - 0
0397 # Back. The device is mounted on the back side of the system, which is
0398 # defined as the opposite side of the front facing one.
0399 - 1
0400 # External. The device is not attached directly to the system but is
0401 # attached in a way that allows it to move freely.
0402 - 2
0403
0404 additionalProperties: true
0405
0406 ...
