1 # SPDX-License-Identifier: (GPL-2.0-only OR BS 1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2 %YAML 1.2 2 %YAML 1.2
3 --- 3 ---
4 $id: http://devicetree.org/schemas/media/video 4 $id: http://devicetree.org/schemas/media/video-interface-devices.yaml#
5 $schema: http://devicetree.org/meta-schemas/co 5 $schema: http://devicetree.org/meta-schemas/core.yaml#
6 6
7 title: Common Properties for Video Receiver an 7 title: Common Properties for Video Receiver and Transmitter Devices
8 8
9 maintainers: 9 maintainers:
10 - Jacopo Mondi <jacopo@jmondi.org> 10 - Jacopo Mondi <jacopo@jmondi.org>
11 - Sakari Ailus <sakari.ailus@linux.intel.com> 11 - Sakari Ailus <sakari.ailus@linux.intel.com>
12 12
13 properties: 13 properties:
14 flash-leds: 14 flash-leds:
15 $ref: /schemas/types.yaml#/definitions/pha 15 $ref: /schemas/types.yaml#/definitions/phandle-array
16 description: 16 description:
17 An array of phandles, each referring to 17 An array of phandles, each referring to a flash LED, a sub-node of the LED
18 driver device node. 18 driver device node.
19 19
20 lens-focus: 20 lens-focus:
21 $ref: /schemas/types.yaml#/definitions/pha 21 $ref: /schemas/types.yaml#/definitions/phandle
22 description: 22 description:
23 A phandle to the node of the focus lens 23 A phandle to the node of the focus lens controller.
24 24
25 rotation: 25 rotation:
26 $ref: /schemas/types.yaml#/definitions/uin 26 $ref: /schemas/types.yaml#/definitions/uint32
27 enum: [ 0, 90, 180, 270 ] 27 enum: [ 0, 90, 180, 270 ]
28 description: | 28 description: |
29 The camera rotation is expressed as the 29 The camera rotation is expressed as the angular difference in degrees
30 between two reference systems, one relat 30 between two reference systems, one relative to the camera module, and one
31 defined on the external world scene to b 31 defined on the external world scene to be captured when projected on the
32 image sensor pixel array. 32 image sensor pixel array.
33 33
34 A camera sensor has a 2-dimensional refe 34 A camera sensor has a 2-dimensional reference system 'Rc' defined by its
35 pixel array read-out order. The origin i 35 pixel array read-out order. The origin is set to the first pixel being
36 read out, the X-axis points along the co 36 read out, the X-axis points along the column read-out direction towards
37 the last columns, and the Y-axis along t 37 the last columns, and the Y-axis along the row read-out direction towards
38 the last row. 38 the last row.
39 39
40 A typical example for a sensor with a 25 40 A typical example for a sensor with a 2592x1944 pixel array matrix
41 observed from the front is: 41 observed from the front is:
42 42
43 2591 X-axis 0 43 2591 X-axis 0
44 <------------------------+ 0 44 <------------------------+ 0
45 .......... ... ..........! 45 .......... ... ..........!
46 .......... ... ..........! Y-a 46 .......... ... ..........! Y-axis
47 ... ! 47 ... !
48 .......... ... ..........! 48 .......... ... ..........!
49 .......... ... ..........! 194 49 .......... ... ..........! 1943
50 V 50 V
51 51
52 The external world scene reference syste 52 The external world scene reference system 'Rs' is a 2-dimensional
53 reference system on the focal plane of t 53 reference system on the focal plane of the camera module. The origin is
54 placed on the top-left corner of the vis 54 placed on the top-left corner of the visible scene, the X-axis points
55 towards the right, and the Y-axis points 55 towards the right, and the Y-axis points towards the bottom of the scene.
56 The top, bottom, left and right directio 56 The top, bottom, left and right directions are intentionally not defined
57 and depend on the environment in which t 57 and depend on the environment in which the camera is used.
58 58
59 A typical example of a (very common) pic 59 A typical example of a (very common) picture of a shark swimming from left
60 to right, as seen from the camera, is: 60 to right, as seen from the camera, is:
61 61
62 0 X-axis 62 0 X-axis
63 0 +------------------------------ 63 0 +------------------------------------->
64 ! 64 !
65 ! 65 !
66 ! 66 !
67 ! |\____)\___ 67 ! |\____)\___
68 ! ) _____ __`< 68 ! ) _____ __`<
69 ! |/ )/ 69 ! |/ )/
70 ! 70 !
71 ! 71 !
72 ! 72 !
73 V 73 V
74 Y-axis 74 Y-axis
75 75
76 with the reference system 'Rs' placed on 76 with the reference system 'Rs' placed on the camera focal plane:
77 77
78 ¸.·˙! 78 ¸.·˙!
79 ¸.·˙ ! 79 ¸.·˙ !
80 _ ¸.·˙ ! 80 _ ¸.·˙ !
81 +-/ \-+¸.·˙ ! 81 +-/ \-+¸.·˙ !
82 | (o) | ! Camera 82 | (o) | ! Camera focal plane
83 +-----+˙·.¸ ! 83 +-----+˙·.¸ !
84 ˙·.¸ ! 84 ˙·.¸ !
85 ˙·.¸ ! 85 ˙·.¸ !
86 ˙·.¸! 86 ˙·.¸!
87 87
88 When projected on the sensor's pixel arr 88 When projected on the sensor's pixel array, the image and the associated
89 reference system 'Rs' are typically (but 89 reference system 'Rs' are typically (but not always) inverted, due to the
90 camera module's lens optical inversion e 90 camera module's lens optical inversion effect.
91 91
92 Assuming the above represented scene of 92 Assuming the above represented scene of the swimming shark, the lens
93 inversion projects the scene and its ref 93 inversion projects the scene and its reference system onto the sensor
94 pixel array, seen from the front of the 94 pixel array, seen from the front of the camera sensor, as follows:
95 95
96 Y-axis 96 Y-axis
97 ^ 97 ^
98 ! 98 !
99 ! 99 !
100 ! 100 !
101 ! |\_____)\__ 101 ! |\_____)\__
102 ! ) ____ ___.< 102 ! ) ____ ___.<
103 ! |/ )/ 103 ! |/ )/
104 ! 104 !
105 ! 105 !
106 ! 106 !
107 0 +------------------------------ 107 0 +------------------------------------->
108 0 X-axis 108 0 X-axis
109 109
110 Note the shark being upside-down. 110 Note the shark being upside-down.
111 111
112 The resulting projected reference system 112 The resulting projected reference system is named 'Rp'.
113 113
114 The camera rotation property is then def 114 The camera rotation property is then defined as the angular difference in
115 the counter-clockwise direction between 115 the counter-clockwise direction between the camera reference system 'Rc'
116 and the projected scene reference system 116 and the projected scene reference system 'Rp'. It is expressed in degrees
117 as a number in the range [0, 360[. 117 as a number in the range [0, 360[.
118 118
119 Examples 119 Examples
120 120
121 0 degrees camera rotation: 121 0 degrees camera rotation:
122 122
123 123
124 Y-Rp 124 Y-Rp
125 ^ 125 ^
126 Y-Rc ! 126 Y-Rc !
127 ^ ! 127 ^ !
128 ! ! 128 ! !
129 ! ! 129 ! !
130 ! ! 130 ! !
131 ! ! 131 ! !
132 ! ! 132 ! !
133 ! ! 133 ! !
134 ! ! 134 ! !
135 ! 0 +------------------------ 135 ! 0 +------------------------------------->
136 ! 0 X-Rp 136 ! 0 X-Rp
137 0 +------------------------------ 137 0 +------------------------------------->
138 0 X-Rc 138 0 X-Rc
139 139
140 140
141 X-Rc 141 X-Rc 0
142 <------------------------------ 142 <------------------------------------+ 0
143 X-Rp 143 X-Rp 0 !
144 <---------------------------------- 144 <------------------------------------+ 0 !
145 145 ! !
146 146 ! !
147 147 ! !
148 148 ! !
149 149 ! !
150 150 ! !
151 151 ! !
152 152 ! V
153 153 ! Y-Rc
154 154 V
155 155 Y-Rp
156 156
157 90 degrees camera rotation: 157 90 degrees camera rotation:
158 158
159 0 Y-Rc 159 0 Y-Rc
160 0 +--------------------> 160 0 +-------------------->
161 ! Y-Rp 161 ! Y-Rp
162 ! ^ 162 ! ^
163 ! ! 163 ! !
164 ! ! 164 ! !
165 ! ! 165 ! !
166 ! ! 166 ! !
167 ! ! 167 ! !
168 ! ! 168 ! !
169 ! ! 169 ! !
170 ! ! 170 ! !
171 ! ! 171 ! !
172 ! 0 +------------------------- 172 ! 0 +------------------------------------->
173 ! 0 X-Rp 173 ! 0 X-Rp
174 ! 174 !
175 ! 175 !
176 ! 176 !
177 ! 177 !
178 V 178 V
179 X-Rc 179 X-Rc
180 180
181 180 degrees camera rotation: 181 180 degrees camera rotation:
182 182
183 0 183 0
184 <------------------------------------+ 184 <------------------------------------+ 0
185 X-Rc ! 185 X-Rc !
186 Y-Rp ! 186 Y-Rp !
187 ^ ! 187 ^ !
188 ! ! 188 ! !
189 ! ! 189 ! !
190 ! ! 190 ! !
191 ! ! 191 ! !
192 ! ! 192 ! !
193 ! ! 193 ! !
194 ! V 194 ! V
195 ! Y-R 195 ! Y-Rc
196 0 +------------------------------ 196 0 +------------------------------------->
197 0 X-Rp 197 0 X-Rp
198 198
199 270 degrees camera rotation: 199 270 degrees camera rotation:
200 200
201 0 Y-Rc 201 0 Y-Rc
202 0 +--------------------> 202 0 +-------------------->
203 ! 203 ! 0
204 ! <------------------------- 204 ! <-----------------------------------+ 0
205 ! X-Rp 205 ! X-Rp !
206 ! 206 ! !
207 ! 207 ! !
208 ! 208 ! !
209 ! 209 ! !
210 ! 210 ! !
211 ! 211 ! !
212 ! 212 ! !
213 ! 213 ! !
214 ! 214 ! V
215 ! 215 ! Y-Rp
216 ! 216 !
217 ! 217 !
218 ! 218 !
219 ! 219 !
220 V 220 V
221 X-Rc 221 X-Rc
222 222
223 223
224 Example one - Webcam 224 Example one - Webcam
225 225
226 A camera module installed on the user fa 226 A camera module installed on the user facing part of a laptop screen
227 casing used for video calls. The capture 227 casing used for video calls. The captured images are meant to be displayed
228 in landscape mode (width > height) on th 228 in landscape mode (width > height) on the laptop screen.
229 229
230 The camera is typically mounted upside-d 230 The camera is typically mounted upside-down to compensate the lens optical
231 inversion effect: 231 inversion effect:
232 232
233 Y-Rp 233 Y-Rp
234 Y-Rc ^ 234 Y-Rc ^
235 ^ ! 235 ^ !
236 ! ! 236 ! !
237 ! ! |\_____)\__ 237 ! ! |\_____)\__
238 ! ! ) ____ ___.< 238 ! ! ) ____ ___.<
239 ! ! |/ )/ 239 ! ! |/ )/
240 ! ! 240 ! !
241 ! ! 241 ! !
242 ! ! 242 ! !
243 ! 0 +------------------------ 243 ! 0 +------------------------------------->
244 ! 0 X-Rp 244 ! 0 X-Rp
245 0 +------------------------------ 245 0 +------------------------------------->
246 0 X-Rc 246 0 X-Rc
247 247
248 The two reference systems are aligned, t 248 The two reference systems are aligned, the resulting camera rotation is
249 0 degrees, no rotation correction needs 249 0 degrees, no rotation correction needs to be applied to the resulting
250 image once captured to memory buffers to 250 image once captured to memory buffers to correctly display it to users:
251 251
252 +------------------------------ 252 +--------------------------------------+
253 ! 253 ! !
254 ! 254 ! !
255 ! 255 ! !
256 ! |\____)\___ 256 ! |\____)\___ !
257 ! ) _____ __`< 257 ! ) _____ __`< !
258 ! |/ )/ 258 ! |/ )/ !
259 ! 259 ! !
260 ! 260 ! !
261 ! 261 ! !
262 +------------------------------ 262 +--------------------------------------+
263 263
264 If the camera sensor is not mounted upsi 264 If the camera sensor is not mounted upside-down to compensate for the lens
265 optical inversion, the two reference sys 265 optical inversion, the two reference systems will not be aligned, with
266 'Rp' being rotated 180 degrees relativel 266 'Rp' being rotated 180 degrees relatively to 'Rc':
267 267
268 268
269 X-Rc 0 269 X-Rc 0
270 <------------------------------------+ 270 <------------------------------------+ 0
271 ! 271 !
272 Y-Rp ! 272 Y-Rp !
273 ^ ! 273 ^ !
274 ! ! 274 ! !
275 ! |\_____)\__ ! 275 ! |\_____)\__ !
276 ! ) ____ ___.< ! 276 ! ) ____ ___.< !
277 ! |/ )/ ! 277 ! |/ )/ !
278 ! ! 278 ! !
279 ! ! 279 ! !
280 ! V 280 ! V
281 ! Y-R 281 ! Y-Rc
282 0 +------------------------------ 282 0 +------------------------------------->
283 0 X-Rp 283 0 X-Rp
284 284
285 The image once captured to memory will t 285 The image once captured to memory will then be rotated by 180 degrees:
286 286
287 +------------------------------ 287 +--------------------------------------+
288 ! 288 ! !
289 ! 289 ! !
290 ! 290 ! !
291 ! __/(_____/| 291 ! __/(_____/| !
292 ! >.___ ____ ( 292 ! >.___ ____ ( !
293 ! \( \| 293 ! \( \| !
294 ! 294 ! !
295 ! 295 ! !
296 ! 296 ! !
297 +------------------------------ 297 +--------------------------------------+
298 298
299 A software rotation correction of 180 de 299 A software rotation correction of 180 degrees should be applied to
300 correctly display the image: 300 correctly display the image:
301 301
302 +------------------------------ 302 +--------------------------------------+
303 ! 303 ! !
304 ! 304 ! !
305 ! 305 ! !
306 ! |\____)\___ 306 ! |\____)\___ !
307 ! ) _____ __`< 307 ! ) _____ __`< !
308 ! |/ )/ 308 ! |/ )/ !
309 ! 309 ! !
310 ! 310 ! !
311 ! 311 ! !
312 +------------------------------ 312 +--------------------------------------+
313 313
314 Example two - Phone camera 314 Example two - Phone camera
315 315
316 A camera installed on the back side of a 316 A camera installed on the back side of a mobile device facing away from
317 the user. The captured images are meant 317 the user. The captured images are meant to be displayed in portrait mode
318 (height > width) to match the device scr 318 (height > width) to match the device screen orientation and the device
319 usage orientation used when taking the p 319 usage orientation used when taking the picture.
320 320
321 The camera sensor is typically mounted w 321 The camera sensor is typically mounted with its pixel array longer side
322 aligned to the device longer side, upsid 322 aligned to the device longer side, upside-down mounted to compensate for
323 the lens optical inversion effect: 323 the lens optical inversion effect:
324 324
325 0 Y-Rc 325 0 Y-Rc
326 0 +--------------------> 326 0 +-------------------->
327 ! Y-Rp 327 ! Y-Rp
328 ! ^ 328 ! ^
329 ! ! 329 ! !
330 ! ! 330 ! !
331 ! ! 331 ! !
332 ! ! |\_____)\__ 332 ! ! |\_____)\__
333 ! ! ) ____ ___.< 333 ! ! ) ____ ___.<
334 ! ! |/ )/ 334 ! ! |/ )/
335 ! ! 335 ! !
336 ! ! 336 ! !
337 ! ! 337 ! !
338 ! 0 +------------------------- 338 ! 0 +------------------------------------->
339 ! 0 X-Rp 339 ! 0 X-Rp
340 ! 340 !
341 ! 341 !
342 ! 342 !
343 ! 343 !
344 V 344 V
345 X-Rc 345 X-Rc
346 346
347 The two reference systems are not aligne 347 The two reference systems are not aligned and the 'Rp' reference system is
348 rotated by 90 degrees in the counter-clo 348 rotated by 90 degrees in the counter-clockwise direction relatively to the
349 'Rc' reference system. 349 'Rc' reference system.
350 350
351 The image once captured to memory will b 351 The image once captured to memory will be rotated:
352 352
353 +------------------------------ 353 +-------------------------------------+
354 | _ _ 354 | _ _ |
355 | \ / 355 | \ / |
356 | | | 356 | | | |
357 | | | 357 | | | |
358 | | > 358 | | > |
359 | < | 359 | < | |
360 | | | 360 | | | |
361 | . 361 | . |
362 | V 362 | V |
363 +------------------------------ 363 +-------------------------------------+
364 364
365 A correction of 90 degrees in counter-cl 365 A correction of 90 degrees in counter-clockwise direction has to be
366 applied to correctly display the image i 366 applied to correctly display the image in portrait mode on the device
367 screen: 367 screen:
368 368
369 +--------------------+ 369 +--------------------+
370 | | 370 | |
371 | | 371 | |
372 | | 372 | |
373 | | 373 | |
374 | | 374 | |
375 | | 375 | |
376 | |\____)\___ | 376 | |\____)\___ |
377 | ) _____ __`< | 377 | ) _____ __`< |
378 | |/ )/ | 378 | |/ )/ |
379 | | 379 | |
380 | | 380 | |
381 | | 381 | |
382 | | 382 | |
383 | | 383 | |
384 +--------------------+ 384 +--------------------+
385 385
386 orientation: 386 orientation:
387 description: 387 description:
388 The orientation of a device (typically a 388 The orientation of a device (typically an image sensor or a flash LED)
389 describing its mounting position relativ 389 describing its mounting position relative to the usage orientation of the
390 system where the device is installed on. 390 system where the device is installed on.
391 $ref: /schemas/types.yaml#/definitions/uin 391 $ref: /schemas/types.yaml#/definitions/uint32
392 enum: 392 enum:
393 # Front. The device is mounted on the 393 # Front. The device is mounted on the front facing side of the system. For
394 # mobile devices such as smartphones, 394 # mobile devices such as smartphones, tablets and laptops the front side
395 # is the user facing side. 395 # is the user facing side.
396 - 0 396 - 0
397 # Back. The device is mounted on the b 397 # Back. The device is mounted on the back side of the system, which is
398 # defined as the opposite side of the 398 # defined as the opposite side of the front facing one.
399 - 1 399 - 1
400 # External. The device is not attached 400 # External. The device is not attached directly to the system but is
401 # attached in a way that allows it to 401 # attached in a way that allows it to move freely.
402 - 2 402 - 2
403 403
404 additionalProperties: true 404 additionalProperties: true
405 405
406 ... 406 ...
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.