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