GNU Linux-libre 5.15.72-gnu
[releases.git] / Documentation / driver-api / media / drivers / sh_mobile_ceu_camera.rst
1 .. SPDX-License-Identifier: GPL-2.0
2
3 Cropping and Scaling algorithm, used in the sh_mobile_ceu_camera driver
4 =======================================================================
5
6 Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de>
7
8 Terminology
9 -----------
10
11 sensor scales: horizontal and vertical scales, configured by the sensor driver
12 host scales: -"- host driver
13 combined scales: sensor_scale * host_scale
14
15
16 Generic scaling / cropping scheme
17 ---------------------------------
18
19 .. code-block:: none
20
21         -1--
22         |
23         -2-- -\
24         |      --\
25         |         --\
26         +-5-- .      -- -3-- -\
27         |      `...            -\
28         |          `... -4-- .   - -7..
29         |                     `.
30         |                       `. .6--
31         |
32         |                        . .6'-
33         |                      .´
34         |           ... -4'- .´
35         |       ...´             - -7'.
36         +-5'- .´               -/
37         |            -- -3'- -/
38         |         --/
39         |      --/
40         -2'- -/
41         |
42         |
43         -1'-
44
45 In the above chart minuses and slashes represent "real" data amounts, points and
46 accents represent "useful" data, basically, CEU scaled and cropped output,
47 mapped back onto the client's source plane.
48
49 Such a configuration can be produced by user requests:
50
51 S_CROP(left / top = (5) - (1), width / height = (5') - (5))
52 S_FMT(width / height = (6') - (6))
53
54 Here:
55
56 (1) to (1') - whole max width or height
57 (1) to (2)  - sensor cropped left or top
58 (2) to (2') - sensor cropped width or height
59 (3) to (3') - sensor scale
60 (3) to (4)  - CEU cropped left or top
61 (4) to (4') - CEU cropped width or height
62 (5) to (5') - reverse sensor scale applied to CEU cropped width or height
63 (2) to (5)  - reverse sensor scale applied to CEU cropped left or top
64 (6) to (6') - CEU scale - user window
65
66
67 S_FMT
68 -----
69
70 Do not touch input rectangle - it is already optimal.
71
72 1. Calculate current sensor scales:
73
74         scale_s = ((2') - (2)) / ((3') - (3))
75
76 2. Calculate "effective" input crop (sensor subwindow) - CEU crop scaled back at
77 current sensor scales onto input window - this is user S_CROP:
78
79         width_u = (5') - (5) = ((4') - (4)) * scale_s
80
81 3. Calculate new combined scales from "effective" input window to requested user
82 window:
83
84         scale_comb = width_u / ((6') - (6))
85
86 4. Calculate sensor output window by applying combined scales to real input
87 window:
88
89         width_s_out = ((7') - (7)) = ((2') - (2)) / scale_comb
90
91 5. Apply iterative sensor S_FMT for sensor output window.
92
93         subdev->video_ops->s_fmt(.width = width_s_out)
94
95 6. Retrieve sensor output window (g_fmt)
96
97 7. Calculate new sensor scales:
98
99         scale_s_new = ((3')_new - (3)_new) / ((2') - (2))
100
101 8. Calculate new CEU crop - apply sensor scales to previously calculated
102 "effective" crop:
103
104         width_ceu = (4')_new - (4)_new = width_u / scale_s_new
105         left_ceu = (4)_new - (3)_new = ((5) - (2)) / scale_s_new
106
107 9. Use CEU cropping to crop to the new window:
108
109         ceu_crop(.width = width_ceu, .left = left_ceu)
110
111 10. Use CEU scaling to scale to the requested user window:
112
113         scale_ceu = width_ceu / width
114
115
116 S_CROP
117 ------
118
119 The :ref:`V4L2 crop API <crop-scale>` says:
120
121 "...specification does not define an origin or units. However by convention
122 drivers should horizontally count unscaled samples relative to 0H."
123
124 We choose to follow the advise and interpret cropping units as client input
125 pixels.
126
127 Cropping is performed in the following 6 steps:
128
129 1. Request exactly user rectangle from the sensor.
130
131 2. If smaller - iterate until a larger one is obtained. Result: sensor cropped
132    to 2 : 2', target crop 5 : 5', current output format 6' - 6.
133
134 3. In the previous step the sensor has tried to preserve its output frame as
135    good as possible, but it could have changed. Retrieve it again.
136
137 4. Sensor scaled to 3 : 3'. Sensor's scale is (2' - 2) / (3' - 3). Calculate
138    intermediate window: 4' - 4 = (5' - 5) * (3' - 3) / (2' - 2)
139
140 5. Calculate and apply host scale = (6' - 6) / (4' - 4)
141
142 6. Calculate and apply host crop: 6 - 7 = (5 - 2) * (6' - 6) / (5' - 5)