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 pathes, 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 that
  40     when the line is unavailable pulls it from the horizontal scaler and
  41     input converter of the current slice.
  42     When no more output can be generated as lines from a next slice would
  43     be needed then all remaining lines in the current slice are converted
  44     and horizontally scaled and put in the ring buffer.
  45     [this is done for luma and chroma, each with possibly different numbers
  46      of lines per picture]
  47
  48 Input to YUV Converter
  49     When the input to the main path is not planar 8bit per component yuv or
  50     8bit gray then it is converted to planar 8bit YUV, 2 sets of converters
  51     exist for this currently one performing horizontal downscaling by 2
  52     before the convertion and the other leaving the full chroma resolution
  53     but being slightly slower. The scaler will try to preserve full chroma
  54     here when the output uses it, its possible to force full chroma with
  55     SWS_FULL_CHR_H_INP though even for cases where the scaler thinks its
  56     useless.
  57
  58 Horizontal scaler
  59     There are several horizontal scalers, a special case worth mentioning is
  60     the fast bilinear scaler that is made of runtime generated mmx2 code
  61     using specially tuned pshufw instructions.
  62     The remaining scalers are specially tuned for various filter lengths
  63     they scale 8bit unsigned planar data to 16bit signed planar data.
  64     Future >8bit per component inputs will need to add a new scaler here
  65     that preserves the input precission.
  66
  67 Vertical scaler and output converter
  68     There is a large number of combined vertical scalers+output converters
  69     Some are:
  70     * unscaled output converters
  71     * unscaled output converters that average 2 chroma lines
  72     * bilinear converters                (C, MMX and accurate MMX)
  73     * arbitrary filter length converters (C, MMX and accurate MMX)
  74     And
  75     * Plain C  8bit 4:2:2 YUV -> RGB converters using LUTs
  76     * Plain C 17bit 4:4:4 YUV -> RGB converters using multiplies
  77     * MMX     11bit 4:2:2 YUV -> RGB converters
  78     * Plain C 16bit Y -> 16bit gray
  79       ...
  80
  81     RGB with less than 8bit per component uses dither to improve the
  82     subjective quality and low frequency accuracy.
  83
  84
  85 Filter coefficients:
  86 --------------------
  87 There are several different scalers (bilinear, bicubic, lanczos, area, sinc, ...)
  88 Their coefficients are calculated in initFilter().
  89 Horinzontal filter coeffs have a 1.0 point at 1<<14, vertical ones at 1<<12.
  90 The 1.0 points have been choosen to maximize precission while leaving a
  91 little headroom for convolutional filters like sharpening filters and
  92 minimizing SIMD instructions needed to apply them.
  93 It would be trivial to use a different 1.0 point if some specific scaler
  94 would benefit from it.
  95 Also as already hinted at initFilter() accepts an optional convolutional
  96 filter as input that can be used for contrast, saturation, blur, sharpening
  97 shift, chroma vs. luma shift, ...
  98