git.sesse.net Git - vlc/blob - modules/video_filter/deinterlace/algo_phosphor.h

   1 /*****************************************************************************
   2  * algo_phosphor.h : Phosphor algorithm for the VLC deinterlacer
   3  *****************************************************************************
   4  * Copyright (C) 2011 the VideoLAN team
   5  * $Id$
   6  *
   7  * Author: Juha Jeronen <juha.jeronen@jyu.fi>
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  22  *****************************************************************************/
  23
  24 #ifndef VLC_DEINTERLACE_ALGO_PHOSPHOR_H
  25 #define VLC_DEINTERLACE_ALGO_PHOSPHOR_H 1
  26
  27 /* Forward declarations */
  28 struct filter_t;
  29 struct picture_t;
  30
  31 /*****************************************************************************
  32  * Data structures etc.
  33  *****************************************************************************/
  34
  35 /* These numbers, and phosphor_chroma_list[], should be in the same order
  36    as phosphor_chroma_list_text[]. The value 0 is reserved, because
  37    var_GetInteger() returns 0 in case of error. */
  38 /** Valid Phosphor 4:2:0 chroma handling modes. */
  39 typedef enum { PC_LATEST = 1, PC_ALTLINE   = 2,
  40                PC_BLEND  = 3, PC_UPCONVERT = 4 } phosphor_chroma_t;
  41 /** Phosphor 4:2:0 chroma handling modes (config item). */
  42 static const int phosphor_chroma_list[] = { PC_LATEST, PC_ALTLINE,
  43                                             PC_BLEND,  PC_UPCONVERT };
  44 /** User labels for Phosphor 4:2:0 chroma handling modes (config item). */
  45 static const char *const phosphor_chroma_list_text[] = { N_("Latest"),
  46                                                          N_("AltLine"),
  47                                                          N_("Blend"),
  48                                                          N_("Upconvert") };
  49
  50 /* Same here. Same order as in phosphor_dimmer_list_text[],
  51    and the value 0 is reserved for config error. */
  52 /** Phosphor dimmer strengths (config item). */
  53 static const int phosphor_dimmer_list[] = { 1, 2, 3, 4 };
  54 /** User labels for Phosphor dimmer strengths (config item). */
  55 static const char *const phosphor_dimmer_list_text[] = { N_("Off"),
  56                                                          N_("Low"),
  57                                                          N_("Medium"),
  58                                                          N_("High") };
  59
  60 /** Algorithm-specific state for Phosphor. */
  61 typedef struct
  62 {
  63     phosphor_chroma_t i_chroma_for_420;
  64     int i_dimmer_strength;
  65 } phosphor_sys_t;
  66
  67 /*****************************************************************************
  68  * Functions
  69  *****************************************************************************/
  70
  71 /**
  72  * "Phosphor" deinterlace algorithm: framerate-doubling CRT TV simulator.
  73  *
  74  * There is no "1x" mode in this filter; only framerate doubling is supported.
  75  *
  76  * There is no input frame parameter, because the input frames
  77  * are taken from the history buffer.
  78  *
  79  * Soft field repeat (repeat_pict) is supported. Note that the generated
  80  * "repeated" output picture is unique because of the simulated light decay.
  81  * Its "old" field comes from the same input frame as the "new" one, unlike
  82  * the first output picture of the same frame.
  83  *
  84  * As many output frames should be requested for each input frame as is
  85  * indicated by p_src->i_nb_fields. This is done by calling this function
  86  * several times, first with i_order = 0, and then with all other parameters
  87  * the same, but a new p_dst, increasing i_order (1 for second field,
  88  * and then if i_nb_fields = 3, also i_order = 2 to get the repeated first
  89  * field), and alternating i_field (starting, at i_order = 0, with the field
  90  * according to p_src->b_top_field_first). See Deinterlace() for an example.
  91  *
  92  * @param p_filter The filter instance. Must be non-NULL.
  93  * @param p_dst Output frame. Must be allocated by caller.
  94  * @param i_order Temporal field number: 0 = first, 1 = second, 2 = rep. first.
  95  * @param i_field Render which field? 0 = top field, 1 = bottom field.
  96  * @return VLC error code (int).
  97  * @retval VLC_SUCCESS The requested field was rendered into p_dst.
  98  * @retval VLC_EGENERIC No pictures in history buffer, cannot render.
  99  * @see RenderBob()
 100  * @see RenderLinear()
 101  * @see Deinterlace()
 102  */
 103 int RenderPhosphor( filter_t *p_filter,
 104                     picture_t *p_dst,
 105                     int i_order, int i_field );
 106
 107 /*****************************************************************************
 108  * Extra documentation
 109  *****************************************************************************/
 110
 111 /**
 112  * \file
 113  * "Phosphor" deinterlace algorithm. This simulates the rendering mechanism
 114  * of an interlaced CRT TV, actually producing *interlaced* output.
 115  *
 116  * The main use case for this filter is anime for which IVTC is not applicable.
 117  * This is the case, if 24fps telecined material has been mixed with 60fps
 118  * interlaced effects, such as in Sol Bianca or Silent Mobius. It can also
 119  * be used for true interlaced video, such as most camcorder recordings.
 120  *
 121  * The filter has several modes for handling 4:2:0 chroma for those output
 122  * frames that fall across input frame temporal boundaries (i.e. fields come
 123  * from different frames). Upconvert (to 4:2:2) provides the most accurate
 124  * CRT simulation, but requires more CPU and memory bandwidth than the other
 125  * modes. The other modes keep the chroma at 4:2:0.
 126  *
 127  * About these modes: telecined input (such as NTSC anime DVDs) works better
 128  * with AltLine, while true interlaced input works better with Latest.
 129  * Merge is a compromise, which may or may not look acceptable.
 130  * The mode can be set in the VLC advanced configuration,
 131  * All settings > Video > Filters > Deinterlace
 132  *
 133  * Technically speaking, this is an interlaced field renderer targeted for
 134  * progressive displays. It works by framerate doubling, and simulating one
 135  * step of light output decay of the "old" field during the "new" field,
 136  * until the next new field comes in to replace the "old" one.
 137  *
 138  * While playback is running, the simulated light decay gives the picture an
 139  * appearance of visible "scanlines", much like on a real TV. Only when the
 140  * video is paused, it is clearly visible that one of the fields is actually
 141  * brighter than the other.
 142  *
 143  * The main differences to the Bob algorithm are:
 144  *  - in addition to the current field, the previous one (fading out)
 145  *    is also rendered
 146  *  - some horizontal lines don't seem to flicker as much
 147  *  - scanline visual effect (adjustable; the dimmer strength can be set
 148  *    in the VLC advanced configuration)
 149  *  - the picture appears 25%, 38% or 44% darker on average (for dimmer
 150  *    strengths 1, 2 and 3)
 151  *  - if the input has 4:2:0 chroma, the colours may look messed up in some
 152  *    output frames. This is a limitation of the 4:2:0 chroma format, and due
 153  *    to the fact that both fields are present in each output picture. Usually
 154  *    this doesn't matter in practice, but see the 4:2:0 chroma mode setting
 155  *    in the configuration if needed (it may help a bit).
 156  *
 157  * In addition, when this filter is used on an LCD computer monitor,
 158  * the main differences to a real CRT TV are:
 159  *  - Pixel shape and grid layout; CRT TVs were designed for interlaced
 160  *    field rendering, while LCD monitors weren't.
 161  *  - No scan flicker even though the display runs (usually) at 60Hz.
 162  *    (This at least is a good thing.)
 163  *
 164  * The output vertical resolution should be large enough for the scaling
 165  * not to have a too adverse effect on the regular scanline pattern.
 166  * In practice, NTSC video can be acceptably rendered already at 1024x600
 167  * if fullscreen even on an LCD. PAL video requires more.
 168  *
 169  * Just like Bob, this filter works properly only if the input framerate
 170  * is stable. Otherwise the scanline effect breaks down and the picture
 171  * will flicker.
 172  */
 173
 174 #endif