Add , to clarify sentence.
[ffmpeg.git] / doc / swscale.txt
1     The official guide to swscale for confused developers.
2    ========================================================
3
4 Current (simplified) Architecture:
5 ---------------------------------
6                         Input
7                           v
8                    _______OR_________
9                  /                   \
10                /                       \
11        special converter     [Input to YUV converter]
12               |                         |
13               |          (8bit YUV 4:4:4 / 4:2:2 / 4:2:0 / 4:0:0 )
14               |                         |
15               |                         v
16               |                  Horizontal scaler
17               |                         |
18               |      (15bit YUV 4:4:4 / 4:2:2 / 4:2:0 / 4:1:1 / 4:0:0 )
19               |                         |
20               |                         v
21               |          Vertical scaler and output converter
22               |                         |
23               v                         v
24                          output
25
26
27 Swscale has 2 scaler paths, each side must be capable to handle
28 slices, that is consecutive non overlapping rectangles of dimension
29 (0,slice_top) - (picture_width, slice_bottom)
30
31 special converter
32     This generally are unscaled converters of common
33     formats, like YUV 4:2:0/4:2:2 -> RGB15/16/24/32. Though it could also
34     in principle contain scalers optimized for specific common cases.
35
36 Main path
37     The main path is used when no special converter can be used, the code
38     is designed as a destination line pull architecture. That is for each
39     output line the vertical scaler pulls lines from a ring buffer. When
40     the ring buffer does not contain the wanted line then it is pulled from
41     the input slice through the input converter and horizontal scaler, and
42     the result is also stored in the ring buffer to serve future vertical
43     scaler requests.
44     When no more output can be generated because lines from a future slice
45     would be needed, then all remaining lines in the current slice are
46     converted, horizontally scaled and put in the ring buffer.
47     [this is done for luma and chroma, each with possibly different numbers
48      of lines per picture]
49
50 Input to YUV Converter
51     When the input to the main path is not planar 8bit per component yuv or
52     8bit gray then it is converted to planar 8bit YUV, 2 sets of converters
53     exist for this currently one performing horizontal downscaling by 2
54     before the conversion and the other leaving the full chroma resolution
55     but being slightly slower. The scaler will try to preserve full chroma
56     here when the output uses it, its possible to force full chroma with
57     SWS_FULL_CHR_H_INP though even for cases where the scaler thinks its
58     useless.
59
60 Horizontal scaler
61     There are several horizontal scalers, a special case worth mentioning is
62     the fast bilinear scaler that is made of runtime generated MMX2 code
63     using specially tuned pshufw instructions.
64     The remaining scalers are specially tuned for various filter lengths
65     they scale 8bit unsigned planar data to 16bit signed planar data.
66     Future >8bit per component inputs will need to add a new scaler here
67     that preserves the input precision.
68
69 Vertical scaler and output converter
70     There is a large number of combined vertical scalers+output converters
71     Some are:
72     * unscaled output converters
73     * unscaled output converters that average 2 chroma lines
74     * bilinear converters                (C, MMX and accurate MMX)
75     * arbitrary filter length converters (C, MMX and accurate MMX)
76     And
77     * Plain C  8bit 4:2:2 YUV -> RGB converters using LUTs
78     * Plain C 17bit 4:4:4 YUV -> RGB converters using multiplies
79     * MMX     11bit 4:2:2 YUV -> RGB converters
80     * Plain C 16bit Y -> 16bit gray
81       ...
82
83     RGB with less than 8bit per component uses dither to improve the
84     subjective quality and low frequency accuracy.
85
86
87 Filter coefficients:
88 --------------------
89 There are several different scalers (bilinear, bicubic, lanczos, area, sinc, ...)
90 Their coefficients are calculated in initFilter().
91 Horizontal filter coeffs have a 1.0 point at 1<<14, vertical ones at 1<<12.
92 The 1.0 points have been chosen to maximize precision while leaving a
93 little headroom for convolutional filters like sharpening filters and
94 minimizing SIMD instructions needed to apply them.
95 It would be trivial to use a different 1.0 point if some specific scaler
96 would benefit from it.
97 Also as already hinted at, initFilter() accepts an optional convolutional
98 filter as input that can be used for contrast, saturation, blur, sharpening
99 shift, chroma vs. luma shift, ...
100